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Terminology used in this document 

Unless otherwise noted in this publication, the following references apply: 

• MVS CICS applies to Customer Information Control System /Enterprise 
Systems Architecture (CICS/ESA) systems. 

• CICS applies to CICS for VSE/ESA, CICS/ESA, CICS for OS/2, CICS for 
AIX, CICS for Windows NT, and CICS for Solaris. 

• CICS for Windows NT refers to IBM TXSeries for Windows NT Version 4.2. 

• CICS for AIX refers to IBM TXSeries for AIX Version 4.2. 

• CICS for Solaris refers to IBM WebSphere Enterprise Edition Version 3.0. 

• IMS/VS applies to Information Management System /Enterprise System 
Architecture (IMS/ESA) and IMS/ESA Transaction Manager systems. 

• IMS applies to IMS/ESA and IMS/ESA Transaction Manager, and to 
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• LE applies to the IBM Language Environment for MVS and VM. 

• COBOL applies to any of the following types of COBOL: 

- IBM VisualAge for COBOL for OS/2 

- ILE COBOL/400 

- IBM COBOL for VSE 

- IBM COBOL for MVS and VM 

• "Region" and "CICS region" correspond to the following: 

- CICS for MVS/ESA region 

- IMS region 

- CICS for VSE/ESA partition 

- CICS for OS/2 system 

- CICS for AIX system 

- CICS for Windows NT system 

- CICS for Solaris system 

• DB2/VSE refers to SQL/DS Version 3 Release 4 or later. Any references to 
SQL/DS refer to DB2/VSE and SQL/DS on VM. In addition, any references 
to SQL/400 refer to DB2/400. 

• OS/2 CICS applies to CICS Operating System/2 (CICS for OS/2). 

• Workstation applies to a personal computer, not an AIX workstation. 

• The make process applies to the generic process not to specific make 
commands, such as make, nmake, pmake, polymake. 

• Unless otherwise noted, references to VM apply to Virtual 
Machine /Enterprise Systems Architecture (VM/ESA) environments. 

• References to VM batch apply to any batch facility running on VM. 

• DB2/2 applies to DB2/2 Version 2.1 or later, and DB2 Universal Database 
(UDB) for OS/2 Version 5. 

• DB2/6000 applies to DB2/6000 Version 2.1 or later, and DB2 Universal 
Database (UDB) for AIX Version 5. 

• Windows applies to Windows 95, Windows 98, Windows NT, and 
Windows 2000. 

• Unless a specific version of Windows NT is referenced, statements 
regarding Windows NT also apply to Windows 2000. 

Terminology differences between Java and Smalltalk 

VisualAge Generator Developer can be installed as a feature of VisualAge for 
Java or VisualAge Smalltalk. Where appropriate, the documentation uses 
terminology that is specific to Java or Smalltalk. But where the information is 
specific to VisualAge Generator and virtually the same for both environments, 
the Java /Smalltalk term is used. 
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Table 1. Terminology differences between Java and Smalltalk 



Java term 


Combined Java/Smalltalk 
term 


Smalltalk term 


Project 


Project/ Configuration map 


Configuration map 


Package 


Package / Application 


Application 


Workspace 


Workspace / Image 


Image 


Beans palette 


Beans/Parts palette 


Parts palette 


Bean 


Visual part or bean 


Visual part 


Repository 


Repository/ENVY library 


ENVY library manager 


Options 


Options / Preferences 


Preferences 
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About this document 



This document provides information on configuring the workstation and 
running Visual Age Generator-generated programs, including the following: 

• VisualAge Generator 32-bit COBOL and C++ programs on OS/2 

• VisualAge Generator C++ programs on Windows NT and CICS for 
Windows NT 

• VisualAge Generator C++ programs on HP-UX 

• VisualAge Generator C++ programs on AIX and CICS for AIX 

• VisualAge Generator C++ programs on Solaris and CICS for Solaris 

For a list of related publications, see "Documentation provided with 
VisualAge Generator". 

Who Should Use This Document 

This document is intended for anyone responsible for running programs on 
VisualAge Generator Server. 

How to Use This Document 

This document contains the following information: 

• Configuring the workstation for CICS OS/2, OS/2, Windows, AIX, HP-UX, 
and Solaris 

• Running COBOL programs on CICS OS/2, including SQL considerations 
and CICS for OS/2 utilities 

• Running C++ programs on OS/2, AIX, CICS for AIX, Windows NT, CICS 
for Windows NT, HP-UX, Solaris and CICS for Solaris 

• Running GUI programs on OS/2 and Windows environments 



Documentation provided with VisualAge Generator 

VisualAge Generator documents are provided in one or more of the following 
formats: 

• Printed and separately ordered using the individual form number. 

• Online book files (.pdf) on the product CD-ROM. Adobe Acrobat Reader is 
used to view the manuals online and to print desired pages. 

• HTML files (.htm) on the product CD-ROM and from the VisualAge 
Generator web page (http://www.ibm.com/software/ad/visgen). 
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The following books are shipped with the VisualAge Generator Developer 
CD. Updates are available from the VisualAge Generator Web page. 

• VisualAge Generator Getting Started (GH23-0258-01) 1,2 

• VisualAge Generator Installation Guide (GH23-0257-01) 1,2 

• Introducing VisualAge Generator Templates (GH23-0272-01) 2,3 

The following books are shipped in PDF and HTML formats on the VisualAge 
Generator CD. Updates are available from the VisualAge Generator Web page. 
Selected books are available in print as indicated. 

• VisualAge Generator Client/Server Communications Guide (SH23-0261-01) 1, 2 

• VisualAge Generator Design Guide (SH23-0264-00) 1 

• VisualAge Generator Generation Guide (SH23-0263-01) 1 

• VisualAge Generator Messages and Problem Determination Guide 
(GH23-0260-01) 1 

• VisualAge Generator Programmer's Reference (SH23-0262-01) 1 

• VisualAge Generator Migration Guide (SH23-0267-00) 1 

• VisualAge Generator Server Guide for Workstation Platforms (SH23-0266-01) 1,4 

• VisualAge Generator System Development Guide (SG24-5467-00) 2 

• VisualAge Generator User's Guide (SH23-0268-01) x ' 2 

• VisualAge Generator Web Transaction Development Guide (SH23-0281-00) 1 

The following documents are available in printed form for VisualAge 
Generator Server for AS/400 and VisualAge Generator Server for MVS, VSE, 
and VM: 

• VisualAge Generator Server Guide for AS/400 (SH23-0280-00) 2 

• VisualAge Generator Server Guide for MVS, VSE, and VM (SH23-0256-00) 2 

The following information is also available for VisualAge Generator: 
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• Migrating Cross System Product Applications to VisualAge Generator 
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• VisualAge Generator Templates V4.5 Standard Functions — User's Guide 
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1. These documents are available as HTML files and PDF files on the product CD. 

2. These documents are available in hardcopy format. 

3. These documents are available as PDF files on the product CD. 

4. This document is included when you order the VisualAge Generator Server product CD. 
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Chapter 1. Preparing to Run CICS for OS/2 COBOL 
Programs on OS/2 



After a VisualAge Generator CICS for OS/2 program is generated, the 
generated objects must be prepared before you can run the program. For CICS 
for OS/2, preparation includes: 

• Preprocessing of EXEC CICS statements in the COBOL program 

• Preprocessing of EXEC SQL statements in the COBOL program 

• Compiling and linking the program 

The COBOL generator creates the control files to perform the preparation 
process and starts the process automatically if requested at generation. 

Refer to the VisualAge Generator Generation Guide for more information on 
preparing programs. The remaining of this section discusses other 
considerations related to running your programs, including: 

• Customizing your workstation for running VisualAge Generator CICS for 
OS/2 programs 

• Distributing prepared programs to other CICS for OS/2 systems 

• Applying SQL program considerations 

• Starting CICS for OS/2 programs 

• Using the VisualAge Generator utilities to convert files and trace program 
activities 

The VisualAge Generator supports generation of IBM VisualAge for COBOL 
for OS/2 code for 32-bit CICS for OS/2 Version 3.0 and higher. 
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Chapter 2. Customizing Your Workstation to Run COBOL 
Programs on OS/2 



Customizing your OS/2 workstation to run CICS OS/2 programs involves 
several tasks. These tasks include the following: 

• Setting environment variables describing the operating environment to the 
running program 

• Defining the CICS transaction work area 

• Defining transactions, programs, and files to CICS 

Optional tasks include modifying the text of VisualAge Generator Server 
messages to meet national language requirements. 



Setting Environment Variables 

VisualAge Generator Server and CICS OS/2 require several environment 
variables to be set. For more information on the environment variables that 
need to be set for VisualAge Generator Server to operate with CICS for OS/2, 
refer to the VisualAge Generator Installation Guide. 

Defining Variables at Run Time 

In VisualAge Generator, values for the required environment variables are 
usually placed in the CONFIG.SYS file during installation. 

To customize your workstation environment with the optional environment 
variables used by VisualAge Generator Server or to change the required 
variables, use one of the following methods: 

• The ELAENV.CMD Command 

This command file is used by VisualAge Generator Server commands and 
utilities to establish their runtime environment. 

The following VisualAge Generator Server programs access ELAENV.CMD: 
- ELARUNC 

• Define them in the CONFIG.SYS file. These values are effective in all OS/2 
sessions. The installation utility can do this for some of the environment 
variables during installation. Others will require manual customization. 

• A different REXX program or an OS/2 command file. 

Note: When you define the environment variables using a command file or 
REXX program, these values are effective only in the OS/2 session 
where the command file or program has previously run. 
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Modifying the Standard OS/2-Defined Variables 

Table 2 shows the standard environment variables that can be customized for 
OS/2 and Common Services. 

Table 2. Standard Environment Variables for OS/2 and Common Services 
Environment variable Runtime services Common services 

DPATH Optional 
HELP 

PATH Required 



The LIBPATH statement must be set in the CONFIG.SYS file. This is required 
by all the Visual Age Generator Server utilities. 

The LIBPATH contains the list of directories that is to be searched for dynamic 
link libraries (DLLs). The name of the product directory where Visual Age 
Generator Server DLL files are located, such as the default location 
C:\VGSVR45\DLL, must appear in the LIBPATH statement in the OS/2 
configuration file, CONFIG.SYS. 

Note: The installation utility modifies this environment variable in the 
CONFIG.SYS file. 

The updated LIBPATH statement should look something like the following: 
LIBPATH=C:\0S2\DLL;C:\IBMC0B0L\DLL;. . . ;C : \VGSVR45\DLL; 

Product-Specific Environment Variables 

Table 3 shows the product-specific environment variables that can be 
customized for CICS for OS/2. 

Table 3. Product Specific Environment Variables for CICS for OS/2 
Environment variable Conversion utility Runtime services 



CICSRGRP 




Optional 


CICSWRK 


Required 


Required 


COBSW 




Required 


EZERCVT 




Optional 


Optional 


ELARTRDB_tttt 




Optional 


EXTFHBUF 


Optional 


Optional 


EZEREDIT 



EZERHSEM 
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Table 3. Product Specific Environment Variables for CICS for OS/2 (continued) 
Environment variable Conversion utility Runtime services 



EZERHTIM 


EZERJULS_xxx 




Optional 


EZERJULL_xxx 




Optional 


EZERGRGS_xxx 




Optional 


EZERGRGL_xxx 




Optional 


EZERNLS 


Optional 


Optional 


EZERSQLDB 




Optional 


EZERSQLDATE 




Optional 


EZERSQLM1 




Optional 


EZERSQLM2 




Optional 


EZERSQLMF 




Optional 


EZERSQLUS 




Optional 


IDXDATBUF 


Optional 


Optional 



For more information on environment variables, see the "Appendix. 
VisualAge Generator Environment Variables" on page 245. Refer to the 
VisualAge Generator Installation Guide for more information on which 
environment variables need to be set for VisualAge Generator Server. 



Adjusting the CICS for OS/2 Transaction Work Area (TWA) Size 

The maximum size of the TWA for CICS for OS/2 must be at least 1024 bytes 
for programs using VisualAge Generator Server runtime services. If you 
generate programs using the TWAOFF option, then the size must be at least 
1024 bytes plus the maximum TWAOFF value specified. Refer to the VisualAge 
Generator Generation Guide for more information about the TWAOFF option. 

The maximum size of the TWA is set in the CICS OS/2 System Initialization 
Table (SIT). Only one SIT is used when a CICS OS/2 system is started. 
Typically, the SIT associated with the FAASYS group is used. The CEDA 
transaction can be used to modify this or another SIT so that the appropriate 
maximum TWA size is used. 

You must stop and start CICS OS/2 again before the new value takes affect. 
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Defining VisualAge Generator Server resources to CICS for OS/2 

The CICS for OS/2 resources associated with VisualAge Generator Server 
need to be defined to CICS for OS/2 so they can be used as part of your CICS 
for OS/2 system. In addition, some CICS for OS/2 system values must be set 
to certain minimum values for generated applications to function properly. 
See the chapter on defining VisualAge Generator Server to CICS for OS/2 in 
the VisualAge Generator Installation Guide for information on how to define 
these resources and sytem values. 

Defining a Program to CICS for OS/2 

Before a program can run in the CICS for OS/2 environment, the program 
and its data files must be defined to CICS for OS/2. 

You must create any new CICS for OS/2 files. See "Creating New CICS for 
OS/2 Files" on page 11 for more information about creating files. 

CICS OS/2 requires that the program dynamic link libraries be in a directory 
listed in the CICSWRK environment variable. In addition, table data files must 
be in a directory listed in the DPATH environment variable. For more 
information on environment variables, see "Appendix. VisualAge Generator 
Environment Variables" on page 245. 

The CICS for OS/2 table entries can be set using the CEDA transaction. 

Other entries may be required if remote programs are called. See the CICS for 
OS/2 documentation for more information. 

If the CICSRGRP environment variable is being used, ensure that the group 
these entries are defined in is included in the CICSRGRP value. 

If the program is distributed using the CICS for OS/2 transactions CAIM and 
CAEX, a PPT entry is required for all files associated with the program. 

Note: CICS for OS/2 must be stopped and started again for new table entries 
to take effect. 

Once the program is defined to CICS for OS/2, do one of the following: 

• Distribute the program to other workstations. See "Chapter 3. Distributing 
VisualAge Generator CICS for OS/2 COBOL Programs on OS/2" on 
page 13 for more information. 

• Rim the program on the local workstation where it was just defined. 

Table Entries Required for CICS for OS/2 Programs 

The following CICS for OS/2 table entries are required for programs: 

• A Program Control Table (PCT) entry (see "PCT Table Entry" on page 9) 
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• A Processing Program Table (PPT) entry (see "PPT Table Entry") 

• A File Control Table (FCT) entry (see "FCT Table Entry" on page 10) 

• A Destination Control Table (DCT) entry (see "DCT Table Entry" on 
page 11) 

PCT Table Entry 

PCT entries are program control table entries. A PCT entry is required for the 
following: 

• Each main program 

• Asynchronous programs you started through CREATX 

• Programs transferred to with an XFER statement 

• Programs referenced by the transaction name in EZESEGTR 

• Programs transferred to by non-VisualAge Generator programs 

PCT entries are required for each transaction code that starts a generated main 
program, including the following transactions: 

• Started from a clear CICS OS/2 screen 

• Used as an EZESEGTR name 

• Used as the target of an XFER or CREATX statement 

• Transferred to from a non-VisualAge Generator program 

• Started by other CICS OS/2 facilities 

• Asynchronous programs started through CREATX 

• Programs that are XFERed to 

• Programs referenced by the transaction name in EZESEGTR 

• Programs transferred to from a non-VisualAge Generator program 

You might need to create a PCT entry for the following, with the specified 
values for these fields: 

• Program 

Transaction code 

Unique 4-character name 

Transaction type 

R (Recoverable) 

PPT Table Entry 

PPT entries are processing program table entries. Create a PPT entry for each 
map group program with print maps. 

A PPT entry is required for all mapping services programs using the values 
described below. In addition, if you plan to use the CAEX transaction to 
distribute a program, a PPT entry is required for each of the following: 

• Program 

Resident P, T, or N depending on use 

Program type P 

• Table 
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Resident N 
Program type P 

• Mapping services programs 
Resident T 
Program type P 

• Map group format modules 
Resident N 
Program type P 

• Custom data conversion table 
Resident N 
Program type P 

FCT Table Entry 

FCT entries are file control table entries. They are required for program files 
that are specified as VSAM files, even if the file is accessed through an 
alternate index. 

The following data is needed for each file entry: 
File name 

The name of the file. This must match the file name used in the 
VisualAge Generator program. 

Group name 

The name of the program group. This should match the group name 
being used for the programs using this file. 

Dataset name 

The complete file name that CICS for OS/2 stores this file under. 
Since CICS for OS/2 uses Btrieve for VSAM file handling, the 
recommended file extension for this file is .BTR. For example: 

C:\CICS3G0\RUNTIME\DATA\MYFILE.BTR 
File open 

This should be set to Y for Yes. VisualAge Generator Server expects 
files to be open prior to their being accessed. 

File enabled 

This should be set to Y for Yes. VisualAge Generator Server expects 
files to be enabled prior to their being accessed. 

File type 

The file type of the file. The following table can be used to convert 
VisualAge Generator file types to CICS for OS/2 file types: 

File type 

E Serial File 

K Indexed File 
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R Relative File 

A Alternate Indexed File 

File Access Method 

This determines whether the file is recoverable if a ROLLBACK is 
required. 

Minimum and Maximum Record Length 

These should be set to the minimum and maximum record lengths. 
For fixed-length records, these values will be the same. 

CI Size 

The control interval. For files other than alternate index files, this 
must be specified. Valid values are multiples of 512. 

Key segments 

The key segments define the keys in an indexed file. See the CICS for 
OS/2 documentation for specific information on defining keys in an 
FCT entry. 

DCT Table Entry 

DCT entries are destination control table entries. They are required for 
program files that are assigned to a transient data queue and for destinations 
specified as ERRDEST names. Create a DCT entry for each file assigned to a 
transient data queue. 

You might need to create a DCT entry for the following, with the specified 
values for these fields: 

• Input/Output file or ERRDEST file 
Recoverable queue Y 

Creating New CICS for OS/2 Files 

If an FCT entry is created for a file that does not exist, VisualAge Generator 
Server will not create the file. This file must be created before any programs 
using the file are run. 

To create a new data file for CICS for OS/2, do the following: 

1 . Define an FCT entry (see "FCT Table Entry" on page 10) for the file. 

2. Stop CICS for OS/2 and restart it so that the file entry is available. 

3. Use the CECI transaction to open and enable the file. 

To open a file, type: 

CECI SET FILE ( filename ) OPEN RESET 

To enable a file, do the following: 

1 . From CECI, press F5 to define a variable. 
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2. Define &STATUS to be type F (Fullword). 

3. Press Enter so that &STATUS is created. 

4. Give &STATUS a value of 23 (Enabled). 

5. On the top line of the console, type the following: 

SET FILE (filename) ENABLESTATUS (&STATUS) 

For more information on defining a program to CICS for OS/2, refer to your 
CICS for OS/2 documentation. 



Customizing the VisualAge Generator Server Runtime Messages 

This section discusses customizing runtime messages. Runtime messages 
report that a condition that is not handled by a program has occurred. These 
messages can be modified to provide more information to the user. 

Error messages that are used by the generated COBOL programs provided 
with VisualAge Generator Server are stored in ELAMxxx.TAB. This file 
contains default messages that should be acceptable for most situations. 

If you elect to customize these messages, do the following: 

1 . Import the external source format source information containing the 
VisualAge Generator Servererror messages into an library. 

This external source format information is available as ELACxxx.ESF on 
the workstation in the C:\VGSEVR2\SAMPLES directory. 

2. Use the VisualAge Generator Developer to change the message text, which 
is in the second column in the table. 

Ensure that you do not modify anything other than this column. The order 
of message inserts can change, but the number and format specifications 
for the message inserts must not be changed. 

3. Using VisualAge Generator Developer, generate a new message table for 
the CICS OS/2 environment. 

4. Make a backup copy of the current message table files. 

5. Delete the existing message table files. 

6. Copy the new message table files into the appropriate location. 

7. Your customized message table will be in effect the next time you start 
CICS OS/2. You can also use the New Copy utility to cause the new 
message table to be picked up while CICS OS/2 is running. 

Refer to the online helps for more information about using the New Copy 
utility. 
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Chapter 3. Distributing VisualAge Generator CICS for OS/2 
COBOL Programs on OS/2 



You can distribute a program to multiple workstations using several methods. 
They are as follows: 

• Individual files associated with the prepared program can be transferred to 
other workstations. 

• A CICS for OS/2 CAEX transaction can be used to combine all of the files 
and resource tables associated with a program into an export file. This 
export file can be transferred to other workstations. 

Files in either method can be distributed by copying to a diskette, by 
transferring through a local area network (LAN), by transferring to a host 
system, or any other method for transferring files. 

You can use another CICS OS/2 system to distribute the program. You can 
use the CAEX transaction to export the program and the CAIM transaction to 
import the program to the various CICS for OS/2 workstations, if: 

• All of the workstations that you want to distribute the program to have 
access to a CICS host system 

• The CAEX transaction is set up to export directly to that CICS host system. 

Refer to your CICS for OS/2 documentation for more information on 
distributing programs using a CICS host system. 



Distributing a Program Using CAEX 

The CICS for OS/2 CAEX transaction can be used to distribute a program and 
its associated files. You can use this method to distribute the following: 

• All VisualAge Generator programs, map groups, and tables with a PPT 
entry defined. 

• All VSAM data files with an FCT entry defined. 

CAEX will not distribute the following: 

• Databases defined on this workstation. 

• Environment variable settings on this workstation, including CICSWRK, 
ELARTRDBjttt, and CICSRGRP. 

• COBOL I/O data files. 

Before you can use the CAEX transaction to distribute a program, you must 
do the following: 
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• In CICS for OS/2, verify that the PPT or FCT entries have been defined for 
all of the files that you need to distribute. For more information, see CICS 
table entries "Creating New CICS for OS/2 Files" on page 11. 

• While examining the table entries, make a note of the program groups 
under which these table entries are defined. 

• Start CADL 

Starting the CADL Transaction 

The CADL transaction lists the program groups currently exported to the 
import and export file, FAAAEFIE. You can delete some or all of these 
program groups from CADL. 

To start the CADL transaction, do the following: 

1 . If you have logged off CICS for OS/2, start CICS for OS/2. Then, log on 
to CICS for OS/2 with a user ID authorized to use tables, such as the 
default user ID, SYSAD. 

Note: You can use the CESN transaction to log on to the CICS for OS/2 
system. 

2. Start the CADL transaction. 

3. Determine if you need to delete any previously exported groups from the 
import and export file, FAAAEFIE groups that you do not want to 
distribute with the new program group. 

Note: 

FAAAEFIE is the name of the file control table (FCT) entry that is used as 
the target for the CAEX and CAIM transactions. Using CAEX, you can 
export one or more program groups to this file. Using CAIM, you can 
select which program groups to import. 

You can view and delete the groups in this file using the CADL 
transaction. 

If you want to use a different file name as the import and export file, do 
the following: 

a. Change the FCT entry for FAAAEFIE to a new name. 

b. Log off and close CICS for OS/2. 

c. Start CICS for OS/2; then log on to the user ID, SYSAD. 

d. If this is a new export file, use the CECI transaction to open the file 
and reset it. 

4. Exit the CADL transaction. 

5. Start the CAEX transaction. 
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The CAEX transaction exports program groups to the file pointed to by 
the FAAAEFIE FCT entry. This file can be a CICS for OS/2 VSAM or host 
VSAM file accessed using a CICS host system. 

Refer to your CICS for OS/2 documentation for more information on 
exporting to host VSAM files. 

6. Type the name of the program group that you want to export; then press 
Enter. 

An program group specifies the programs, files, and resources that are in 
a group of related programs. For every entry in a resource table, you 
must specify the group that the entry belongs to. If you want to 
distribute a set of programs, files, or resources as a single unit, you need 
to assign them to the same program group. 

7. Exit the CAEX transaction. 

8. Stop CICS for OS/2 so that CICS for OS/2 releases the export file. 

Note: CQIT will shut down the entire CICS for OS/2 system. 

For additional information about the CICS for OS/2 environment, refer to 
your CICS for OS/2 documentation. 

The export file now contains the complete program, its related CICS for 
OS/2 table entries, any data files that are associated with the FCT entries, 
and any message files that are assigned to the program group. The 
location of the export file is specified in the FAAAEFIE FCT entry. If this 
value has not changed, the exported file is named FAAAEFIE.BTR in 
your CICS for OS/2 data directory. 

9. Change the directory to the location where the export file is located. 

10. Transfer the export file to the location that it will be distributed from. 
This can be a diskette, LAN, MVS host system, or other location. 

The file can now be distributed to multiple workstations with VisualAge 
Generator Server and CICS for OS/2 installed. 

Importing an Exported Program Using the CAIM Transaction 

After the program is distributed to the appropriate workstations, the program 
must be installed to run on those workstations. 

You can use the CAIM (see "Distributing a Program Using CAEX" on page 13) 
transaction to install a prepared program, but only if it was distributed by 
exporting the program using the CAEX transaction. Refer to your CICS for 
OS/2 documentation for more information. 
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Note: The CAIM transaction imports program groups from the file pointed to 
by the FAAAEFIE FCT entry. This file can be a CICS for OS/2 VSAM 
file or a host VSAM file accessed using a CICS host system. 

To install the program, you must complete the following steps: 

1 . On the workstation where you want to run the program, transfer the 
export file to the CICS for OS/2 data directory. 

The export file should be named FAAAEFIE. BTR and the name must 
match the FCT entry for the FAAAEFIE file on this system. 

2. Start CICS for OS/2; then log on to CICS for OS/2 with a user ID 
authorized to use tables, such as the default user ID, SYSAD. 

You can use the ELARUNC command to start CICS for OS/2 so that the 
environment is set up for VisualAge Generator Server. 

3. Start the CAIM transaction to import the program group from the export 
file, FAAAEFIE. The CAEX transaction exports program groups to the file 
pointed to by the FAAAEFIE FCT entry. This file can be a CICS OS/2 
VSAM or host VSAM file accessed using a CICS host system. 

Refer to your CICS OS/2 documentation for more information on 
exporting to host VSAM files. 

If you are using the CICSRGRP environment variable and the imported 
program group or groups are not defined in it, you need to stop CICS for 
OS/2 and add the imported groups to the CICSRGRP value. When CICS 
for OS/2 is restarted, the imported groups will be available. 

The program is now installed and you can run the program after CICS for 
OS/2 is stopped and restarted. 

If you are installing a program that has SQL statements, see "Chapter 4. 
Considerations for COBOL SQL Programs on OS/2" on page 17, which is the 
next topic of discussion. 



16 VisualAge Generator: VisualAge Generator Server Guide for Workstation Platforms 



Chapter 4. Considerations for COBOL SQL Programs on 
OS/2 



A program must be prepared before it can run. The following sections provide 
information for preparing programs using SQL statements: 

• Environment Variables 

• Preparing SQL Programs 

• Building an Access Plan 

• Code Page Considerations 

• Static Versus Dynamic SQL Statements 

• Using DDCS/2 

• Default Databases for SQL Programs 

• Accessing Distributed Databases 

• CICS OS/2 Syncpoint Coordination 



Environment Variables 

The following environment variables are referenced in preparing and running 

a program containing SQL statements: 

EZERSQLDB 

The VisualAge Generator Server default database. 
EZERSQLDATE 

The SQL date and time format indicator. 
EZERSQLM1 

Indicates that VisualAge Generator Server is to start a database again 
if it was left in an uncommitted state. 
EZERSQLM2 

Indicates whether VisualAge Generator Server is to create an access 
plan if one is not available. 
EZERSQLMF 

The default location for BIND messages if an error occurs. 
EZERSQLUS 

The default access mode for SQL databases. 
ELARTRDB_tttt 

The name of the relational database to be connected to a specific 

generated program. 

For more information on setting environment variables, see 
"Appendix. VisualAge Generator Environment Variables" on page 245. 
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Preparing SQL Programs 

Before you can run a program that contains SQL statements, the program 
must be known to the database and be linked to the SQL libraries provided 
with your database manager. 

Access to DB2/2 

The database that the program uses must exist and be known by DB2/2. Refer 
to your database manager documentation for more information on creating a 
database. 

Before you can prepare SQL programs, you must provide a value for the 
environment variable EZERSQLDB, which specifies the default database you 
want to use when preprocessing embedded SQL statements in generated 
programs. For more information on the environment variables EZERSQLDB, 
see "Appendix. VisualAge Generator Environment Variables" on page 245. 

To prepare an SQL program, you must do the following: 

• Have READ authority to each table the program uses. Contact your 
database administrator to ensure you have READ authority. 

• Have WRITE authority if your program writes to the database when it 
runs. 

Linking SQL Programs 

Programs that use SQL must be linked to the SQL libraries provided with 
your database manager. A 32-bit version must be used with IBM VisualAge 
for COBOL for OS/2 programs. 



Building an Access Plan 

An access plan must be built for each database a program uses before an SQL 
program can run successfully. The process is called binding the program. The 
access plan can be built at three different times: 

• If an access plan is not available at run time, VisualAge Generator Server 
attempts to build the access plan the first time the program accesses the 
database. 

If the environment variable EZERSQLM2 is set to NO, VisualAge Generator 
Server does not attempt to build the access plan. The default value of 
EZERSQLM2 is YES. 

• To build the access plan before run time, transfer the bind file, 
progname.BNT), to the workstation where the program will rim. Then issue 
the following BIND command under DB2 command line processor: 

BIND progname. BND 

Where, progname. BND specifies the name of the program you want to run. 
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If you do not specify a file name, the messages are directed to the standard 
output. 

• To build the access plan as part of the preparation process, the program 
must be prepared on the same workstation that it will run on. Building the 
access plan during the preparation process only builds the plan for the 
database that the program is compiled against. For databases that are 
accessed using EZECONCT you must use another method. 

If you are using VisualAge Generator Developer to generate your program, 
refer to the VisualAge Generator Generation Guide for more information. Refer to 
the Database 2 OS/2 Command Reference for more information on the BIND 
command. 



Code Page Considerations 

All SQL programs that use a relational database must use the same code page. 
When you create an SQL database in DB2 / 2, the code page of the process that 
creates the database is associated with the SQL database. 



Static Versus Dynamic SQL Statements 

When unqualified table names are used in the SQL statements of a VisualAge 
Generator program, the implicit table qualification may be different for static 
mode SQL statements than for dynamic mode SQL statements. 

In static mode, SQL statements are resolved when the program is bound. All 
unqualified SQL table names are qualified with the USERID that is logged on 
to the workstation when the bind takes place. 

In dynamic mode, SQL statements are resolved while the program is running. 
All unqualified SQL table names are qualified with the USERID that is logged 
on to the workstation where the program is running. 

Dynamic mode is used in the following situations: 

• When the Execution Time Statement Build option is specified for SQL 
statements in a generated program 

• When the table name of an SQL row record is defined as a host variable 

For more information on static mode versus dynamic mode, refer to the 
VisualAge Generator Design Guide. 

Default Databases for SQL Programs 

The database that an SQL program uses is determined by the settings of 
several environment variables. 
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ELARTRDB_tttt 

Specifies the database to be used by a specific transaction 
EZERSQLDB 

Specifies the VisualAge Generator default database 
SQLDBDFT 

Specifies the DB2/2 SQL default database 

These environment variables are optional. The SQL program behaves 
differently depending on which method is used to select the database that is 
used by a program. 

For more information on the above environment variables, see "Appendix. 
VisualAge Generator Environment Variables" on page 245. 

For more information on DB2/2 default databases and their usage, refer to 
your DB2/2 documentation. 

Determining Which Database Is Used 

If ELARTRDB_tttt is set to a database alias, the program running under the 
Transaction ID specified in tttt uses this name as the database to connect to. If 
ELARTRDB_tttt is not set, the program uses a default database. 

If EZERSQLDB is set to a database alias, the default database for VisualAge 
Generator programs is this database. 

If EZERSQLDB is not set or is set to blanks, the program enables DB2/2 to 
handle the default database connections. 

The program must explicitly connect to a database using the EZECONCT 
environment variable before performing any SQL statement. 

Note: If EZERSQLDB is set and you want a specific transaction to use the 
DB2/2 SQL default database, you can set ELARTRDB_tttt to blanks. 

For more information on the above environment variables, see "Appendix. 
VisualAge Generator Environment Variables" on page 245. 

Differences in Database Behavior 

If the ELARTRDB_tttt or EZERSQLDB environment variable is used to specify 
the database name, the first SQL program in the run unit connects to the 
specified database when the program is initialized. Also, following an 
EZECONCT RESET, the program immediately connects to this database again. 

If the DB2/2 SQL default database is used, DB2/2 performs an implicit 
connect when the run unit performs its first SQL statement. Also, following an 
EZECONCT RESET, the program immediately connects to this database again. 
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Note: Because DB2/2 is handling the connection, the default access mode 
specified by the EZERSQLUS environment variable is not used. All 
databases connected using implicit connect are connected in SHARED 
mode. 

For more information about implicit connect, see your DB2/2 documentation. 



Accessing Distributed Databases 

The IBM Distributed Database Connection Services /2 licensed program 
provides access to any database manager enabled as a Distributed Remote 
Database Architecture (DRDA) server, including all members of the DB2 
product family. 

The DB2 Client Program Enabler/2 licensed program provides access to DB2 
workstation databases, including DB2 and DB2/2. DB2 CAE/2 in conjunction 
with IBM Datajoiner running on OS/2 provides access to non-IBM relational 
databases, including Oracle and Sybase databases. 

DDCS/2 and DB2 CAE/2 provide the same interface for binding and running 
programs that DB2/2 does. Refer to these products' documentation for more 
information. 



CICS OS/2 Syncpoint Coordination Function 

Starting with version 2, CICS for OS/2 provides a syncpoint coordination 
function to facilitate coordinating CICS syncpoints with external resources, 
such as DB2/2. This function requires that a User Installed Module (UIM) be 
used to register its interest in syncpoints and handle any syncpoint requests. 

VisualAge Generator Server coordinates commits and rollbacks between 
DB2/2 and CICS for OS/2 without the need for a UIM. 

If the CICS for OS/2 syncpoint coordination function is already being used, 
data integrity will not be affected. 
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Chapter 5. Running VisualAge Generator COBOL Programs 
on OS/2 



You can start CICS for OS/2 so that the VisualAge Generator Server 
environment is defined for running VisualAge Generator programs by doing 
either of the following: 

• Double-click on the Start CICS for OS/2 with VisualAge Generator icon in 
the VisualAge Generator Server (English) folder on the desktop. 

• Enter the ELARUNC command at an OS/2 command prompt. 

Note: The ELARUNC.CMD is primarily a sample file. Before you use it, 
validate the file and make any necessary changes. 

To run a program under CICS for OS/2, start a CICS OS/2 terminal and enter 
the name of the transaction associated with the program. Refer to your CICS 
for OS/2documentation for other methods for starting transactions. 



ELARUNC Command 

The ELARUNC.CMD file starts CICS for OS/2 and sets up the environment 
required to support running VisualAge Generator Server programs. 
ELARUNC functionally replaces the CICSRUN.CMD file that is supplied with 
CICS for OS/2 because you can use the same parameters with ELARUNC as 
with CICSRUN. By default, ELARUNC is installed in the directory 
C:\VGSVR45\EXE. 

Note: For more information, refer to the VisualAge Generator Installation Guide 
document. 

For more information on setting environment variables, see the "Setting 
Environment Variables" on page 5. 

Performance Considerations 

It is recommended that all internal runtime services temporary storage queues 
remain unrecoverable. 

If the CICS for OS/2 system is being used primarily for VisualAge Generator 
Server programs, consider making ELARSVCS.DLL and ELASSSQL.DLL 
permanent residents in the CICS for OS/2 system. The ELARSVCS.DLL and 
ELASSSQL.DLL files are the primary files of the VisualAge Generator Server 
runtime support. These files can be made permanent residents by creating a 
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PPT entry for these files which specifies that they are permanently resident 
programs. In addition, the C:\VGSVR45\DLL directory needs to be added to 
the value of the CICSWRK environment variable. 

Start your database manager before you start VisualAge Generator Server so 
that it is already initialized and ready for use. Otherwise, performance will be 
slow when the VisualAge Generator Server attempts to start it the first time it 
processes an SQL statement. 



National Language Versions Considerations 

VisualAge Generator Server provides support for more than one national 
language. You can install multiple language versions of VisualAge Generator 
Server on one workstation, although only one language can be loaded each 
time the product is started. VisualAge Generator Server supports double-byte 
character sets on those workstations that provide double-byte support. 

You can address the language version needs of your organization under the 
following conditions: 

• When a program is generated 

• When CICS for OS/2 is started for the Diagnostic Control Options Utility 
(EL AC) and Diagnostic Message Printing Utility (ELAU). The language 
version is determined by the environment variable EZERNLS. 

VisualAge Generator Server does not perform run time code page switching 
or data translation to make the process, keyboard, and display devices 
conform to the language being used. You must configure the appropriate code 
page for VisualAge Generator Server to run and to translate data correctly 
when importing data from an external source format file. Refer to the OS/2 
User's Guide for more information on managing country code information and 
code page switching. 

For more information on SQL programs, see "Code Page Considerations" on 
page 19. 
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Chapter 6. Utilities 



This section provides information on the utilities you can use to do the 
following: 

• Manage error diagnosis and control facilities for the runtime environment 

• Trace program activity 

CICS OS/2 Utilities 

VisualAge Generator Server provides a set of utilities to help manage the 
error diagnosis and control facilities of the runtime environment. 

To start the utilities, type the following transaction code at a clear CICS 
screen: 
ELAM 

The three functions available from the CICS Utilities Menu follow: 
New Copy 

Causes a new copy of a table to be used by subsequent transactions. 
Use the new copy function when you modify or generate programs, 
map groups, and tables again. 

Diagnostic Message Printing Utility 

Routes the diagnostic messages in an error destination transient data 
queue to a printer or OS/2 file for printing. 

Diagnostic Control Options 

Helps you view or change the diagnostic control options set for the 
installation or for individual transactions. The options include dump 
control, error message routing to a transient data queue or the CICS 
for OS/2 journal, and transaction disabling on serious failures. 

New Copy Utility 

The New Copy utility causes a new copy of a table to be used by subsequent 
transactions. Transactions that are already in progress when New Copy is 
started will continue to use the copy that was current when the transaction 
began. Programs must stop or reach the end of a segment before the new 
copy can be used. You must run the New Copy utility separately for 
programs, map groups, and tables to replace the copy already in storage. 

You can start the New Copy Utility by doing one of the following: 

• Select New Copy on the CICS Utilities Menu 

• Type ELAN at a clear CICS window 
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In the Table name field, type the name of the table you want a new copy of. 
The command accesses a new copy of the table program and sets a flag for 
VisualAge Generator Server indicating that the new copy of the table is to be 
used the next time a program loads the table contents. 

If the table is generated as a shared table, transactions currently running 
continue to use the old copy of the table while new transactions shares the 
new copy of the table. 

Diagnostic Message Print Utility 

The diagnostic message print utility routes diagnostic messages in an error 
destination transient data queue to a printer or OS/2 file for printing. 

To start the utility, type the following transaction code at a clear CICS 
window: 

ELAU 

Error destination queue name 

Specifies the name of an existing error destination. Type the 1 to 4 
character DCT name of the ERRDEST error destination transient data 
queue. The queue name is initialized to the default error destination 
queue. The default is ELAD. You can either leave the messages in the 
queue or delete them after they are printed. 

OS/2 Printer or File Information 

Specifies whether the messages are sent to a printer or saved in a file. 
If you send the messages to the printer, specify the printer port 
identifier. The default is LPT1 unless a file name is specified. If you 
want the messages saved to a file, specify the OS/2 file name. The file 
created is a standard ASCII file with carriage returns and line-feed 
characters to help print the file. 

Clear destination queue 

Specifies whether to clear the error queue of all messages after the 
messages are written to a printer file. The default is Y. 

Diagnostic Control Options Utility 

The diagnostic control options utility enables you to change the diagnostic 
action options taken for a given transaction code that is assigned to a 
generated CICS for OS/2 program. If multiple transaction codes are assigned 
to a program, each transaction code is specified independently to the 
diagnostic control options utility. 

You can also specify a default action to take place for transactions that are not 
explicitly defined to the diagnostic control options utility. 

To access the diagnostic control options utility, type ELAC at a clear CICS 
screen. 
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The Diagnostic Control Options utility controls the following actions: 



Change or View Diagnostic Control Options for a Transaction 

To change or view the diagnostic options for a specific transaction 
code. 

Change or View Default Diagnostic Control Options 

To change or view the installation default diagnostic options. This 
affects transaction codes that are not specifically identified to the 
diagnostic controller. 

Change or View Diagnostic Control Options for a Transaction 

With this function you can change the VisualAge Generator Server for 
MVS, VSE, and VM error diagnostic and control options in effect for a 
specific CICS for OS/2 transaction. 

Change or View Diagnostic Control Options for a Transaction controls the 
following actions: 

Transaction ID 

Specifies the 1- to 4- character identifier of the transaction you want to 
change the diagnostic options for. 

Diagnostic Control Options 

The following are the Diagnostic Control Options: 

Transaction ABEND Dump 

Specifies the type of dump taken on an CICS transaction 
ABEND. The types of dumps are: 

1 . No dump 

2. Complete CICS dump 

3. Task dump 

Runtime Error Dump 

Specifies the type of dump taken on a VisualAge Generator 
Server for MVS, VSE, and VM-detected error for which a 
dump is indicated in the error message explanation. The types 
of dumps are as follows: 

1 . No dump 

2. Complete CICS dump 

3. Task dump 

Error Destination Queue Names 

Specify one or two names of the transient data queues where 
you want the diagnostic messages written. You can specify 
both a workstation location and a remote host location. If this 
field is left blank and you change the option, no messages are 
written to a queue. 
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Disable on Run Unit Failure 

Specifies whether a transaction is disabled when an error is 
detected that is likely to occur each time the transaction is 
run. 

Y Specifies that the transaction is disabled when these 

errors are detected. 
N Specifies that the transaction is not be disabled. 

Action 

Change the current options, view the current options, or accept the 
default options. 

Change or View Default Diagnostic Control Options 

You can change or view the default diagnostic options for transactions that 
are not identified to the diagnostic controller. If your default options are not 
modified at installation, they are set as follows: 

• Transaction ABEND and runtime errors will both cause a task dump 

• The error destination queue name is ELAD 

• Transactions are not disabled on a rim unit failure 

The options on this panel are the same as those defined for changing or 
viewing the diagnostic control options for a transaction. 
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Part 2. Running VisualAge Generator C++ programs 
OS/2 
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Chapter 7. Preparing to Run C++ Programs on OS/2 



Visual Age Generator Server enables you to prepare and run C++ programs in 
the OS/2 environment. 

This section contains information needed to prepare a generated C++ program 
to run in an OS/2 environment. During generation, several output files are 
created. These files are used when preparing your programs. 

The preparation step can be invoked by the program generator by specifying 
the Start preparation command file option in the options notebook, or by 
specifying the /PREP option when generating from the command line. 



Generation Output Files 

The output files created at generation are placed in the generation output 
directory or the current directory if the / GENOUT option is not specified. See 
the VisualAge Generator Generation Guide for a list of these files and how to 
generate them. 



Preparing Your C++ Program 

You must prepare your C++ programs before they can be run. This 
preparation step involves compiling and linking the program and map source 
files into executable DLLs. 

Your C++ programs are compiled using the IBM VisualAge C++ compiler. We 
also use the nmake utility that comes with the compiler, nmake accepts as 
input a makefile which lists the source code and instructions for compiling 
and linking this source code. VisualAge Generator Server provides a makefile 
called FCWMAKE that contains instructions on how to compile and link the 
generated programs. 

There are two methods you can use to prepare your C++ generated programs: 

• Use the GENERATE subcommand and have the generator do the prepare. 
This will compile all the parts of the program (programs, map groups, and 
tables). 

• Use the PREPARE subcommand. If generation and preparation are being 
done on the same system, the parts will be compiled and linked. 
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Preparing Programs Using the Generate Subcommand of the HPTCMD 
Command 

The preparation process is automatically started by generation unless you 
specify the /NOPREP option on the GENERATE command or did not specify 
Start preparation command file in the options notebook. 

If you choose this method to do your preparation, be sure that the 
FCWMAKE environment variable contains the name of the directory where 
the VisualAge Generator Server product was installed. This environment 
variable is set in the CONFIG.SYS file if you choose to have it updated during 
installation. 

Preparing Programs Using the PREPARE Subcommand of the HPTCMD 
Command 

You may choose to run the preparation process independently from the 
generation process. To do this, specify the PREPARE subcommand . 

The PREPARE subcommand can only be issued through the VisualAge 
Generator program generator command line interface. The interactive interface 
does not support the PREPARE subcommand. 

The preparation process on OS/2 involves compiling the program, and all of 
its dependents, and then linking them to create a DLL for the program, map 
group, and help map group. The program can then be run using the fcwrun 
command: 

fcwrun progname 

Where progname is the name of the program. 



Understanding Compiled Output Files 

The outputs you receive from program preparation are dynamic link libraries 
(DLLs) which, along with the .TAB files for tables, constitute the executable 
code for the program. The following DLLs are created for each program: 

progname.DLL 

progname is the name of the program 

map.DLL 

map is the name of the main map group 
hlp.DLL 

hip is the name of the help map group 

The map.DLL and hlp.DLL are created only if a map group or help map 
group is defined for the program. 
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In addition to the DLL output files, you will receive other files with 
extensions such as OBJ, DEF, MAP, SQC, BND. The .BND file should be saved 
in case the program is moved to another system so that the DB2 program 
package can be bound into the database on that system. All the other files are 
temporary files and can be deleted. 



Storing Program DLLs 

The program DLLs produced at preparation time need to be placed in a 
directory specified in the LIBPATH environment variable in your 
CONFIG.SYS file. The .TAB files need to be placed in a directory specified in 
the DPATH or FCWDPATH environment variable. 
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Chapter 8. Customizing Your Workstation to Run C++ 
Programs on OS/2 

This chapter describes the tasks that need to be performed to set up the 
workstation to run OS/2 programs. These tasks include the following 
program preparation steps: 

• Setting up environment variables 

• Creating a resource association file 



Environment Variable Settings 

Before you can run your programs, you need to perform the following tasks 
to set up the environment variables for the system: 

• Define product-specific environment variables 

• Modify the standard OS/2-defined variables 

If you want to distribute C++ generated programs to other OS/2 systems, you 
need to set the environment variables on those systems too. 

Defining Product-Specific Environment Variables 

VisualAge Generator Server provides environment variables that you can add 
to your CONFIG.SYS or you can set them from the OS/2 command line when 
setting up your environment to run programs. 

Table 4 shows the product-specific environment variables used with generated 
OS/2 C++ programs. 

Table 4. Product Specific Environment Variables for VisualAge Generator Server for 
OS/2 and Common Services 



Environment variable 


Runtime services 


Common services 


CSOTROPT 




Optional 


CSOTROUT 




Optional 


EZERJULS_xxx 


Optional 




EZERJULL_xxx 


Optional 




EZERGRGS_xxx 


Optional 




EZERGRGL_xxx 


Optional 




EZERNLS 


Required 


Optional 


EZERSQLDB 


Optional 





FCWDBNAME_<progname> Optional 
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Table 4. Product Specific Environment Variables for VisualAge Generator Server for 
OS/2 and Common Services (continued) 

Environment variable Runtime services Common services 



FCWDBPASSWORD 


Optional 


FCWDBUSER 


Optional 


FCWDPATH 


Required 


FCWMAKE 


Required 


FCWRSC 


Optional 


FCWOPT 


Optional 


FCWTROPT 


Optional 



FCWTROUT Optional 



A typical environment might contain the following: 

CS0DIR=C:\HPTCS02 

CS0TR0PT=2 

DPATH=C:\VGSERV2; 

EZERNLS=ENU 

EZERSQLDB=SAMPLE 

FCWCOMP=VAC++ 

FCWDBCS=NO 

FCWDBVERSI0N=7 

FCWDIR=C:\VGSERV2 

FCWDPATH=C:\GENOUT 

FCWLIBPATH=C:\GENOUT 

FCWMAKE=C:\VGSERV2 

FCWTR0PT=31 

INCLUDE=C:\HPTCS02\INCLUDE;C:\VGSERV2\INCLUDE;%INCLUDE% 
LIB=C:\HPTCS02\LIB;C:\VGSERV2;%LIB% 
PATH=C:\HPTCS02\EXE;C:\VGSERV2\EXE;%PATH% 
LIBPATH=C:\HPTCS02\EXE;C:\VGSERV2\EXE;%PATH% 

In addition, the value of EZERSQLDATE is used during generation to set the 
DB2 date and time format specified in the SQL preparation commands in 
appZ.CMD. 

For more information on environment variables, see "Appendix. VisualAge 
Generator Environment Variables" on page 245 and the VisualAge Generator 
Installation Guide. 

Modifying the Standard OS/2-Defined Variables 

Your LIBPATH statement should contain the directory where the program 
DLLs are stored. This directory is usually the generation output directory. 

Table 5 on page 37 shows the standard environment variables used with 
generated OS/2 C++ programs that can be customized. 
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Table 5. Standard Environment Variables for OS/2 and Common Services 


Environment variable 


Runtime services 


Common services 


DPATH 


Optional 




HELP 


LIBPATH 


Required 


Required 


PATH 


Required 





Resource Association File 

If the program you are running accesses files, a resource association file must 
be created with an entry for each serial, indexed, message queue or relative 
record defined in the program. The resource association file is also used when 
your program contains printer maps and you want the output directed to a 
file instead of the default output device (for example LPT1). In the OS/2 
environment, VisualAge Generator Server reads the resource association file at 
run time, not at generation time. 

Creating Resource Association Files 

You can create and edit resource association files using a standard editor. You 
can enter options and values in uppercase or lowercase. All of the options can 
span lines. A period at the end of each entry is optional. 

Comments are permitted and can appear anywhere in the file. Comments 
begin with the characters /* and end with the characters */. 

The default resource association file name is FCW.RSC. You can override the 
default file name by specifying the /R parameter at run time or by specifying 
a filename in the FCWRSC environment variable. For more information on 
using the /R option, see "Chapter 10. Running C++ Programs on OS/2" on 
page 47. 

Note: If your program does file I/O, a resource association file is required. If 
you want to redirect the output from a printer map, specify an entry 
for EZEPRINT: 

ASSOCIATE FI LE=EZEPRINT /SYSNAME=d : \output\report .out 

/FILETYPE=SEQ 

The following diagram shows the syntax of the entries in the resource 
association file. 
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— ASSOCIATE — FILE=filename- 



r 



/BASENAME 



^ L/DUpJ C/FI 



LETYPE= 



-BTRIEVE— 
-IBMCOBOL- 
-MFCOBOL— 

-MQ 

-SEQ 



F— I L/KFY^J L/wnFFJ 



-/NOREPLACE- 



/CONTABLE^ L /KEYS J L /NOFF J /REPLACE 



/SYSNAME=system resource name— 1 !— /SYSTEM=forgef system— 1 !— /TEXT 



ASSOCIATE 

Associates the file name specified in a record definition or the printer 
file with the physical file that is used for the record at run time 

FILE Specifies the file name in the record for which you are defining 
system resource association information 

The file name can be EZEPRINT (the print file for the program) or 
one of the file names specified for a serial, indexed, or relative record 
used by the program. 

/BASENAME 

Specifies the name of the primary key file when using IBMCOBOL 
files. 

If the IBMCOBOL file has secondary keys, a separate entry with a 
unique filename (/SYSNAME) is needed in the resource association 
file for each key definition with the BASENAME keyword referencing 
the primary key file. An alternate index file is created for each 
secondary key and it is associated with the primary key file. 

For example, if the file had a primary key and two secondary keys, 
you would specify the following in the resource association file: 

associate file=empmastr /filetype=ibmcobol /sysname=vsam.dat 

associate file=empaltl /filetype=ibmcobol /sysname=vsamal tl.dat 

/basename=vsam.dat 

associate fi 1 e=empal t2 /filetype=ibmcobol /sysname=vsamal t2.dat 

/basename=vsam.dat 



/DUP 



If duplicates are allowed on any of the keys, specify the /DUP 
keyword for that particular entry. 

Specifies that duplicate record keys will be allowed for IBMCOBOL 
and MFCOBOL indexed files. BTRIEVE files use the /KEYS option to 
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indicate whether duplicate keys are allowed. This option must be 
specified when the file is created. The default is to not allow duplicate 
keys. 

/FILETYPE 

Specifies the implementation of the file in a target environment 

The valid file types are system-dependent. Table 6 on page 41 shows 
the valid file types for the OS/2 environment. 

The file type can be one of the following: 

BTRIEVE 

Specifies an indexed or serial file associated with a Btrieve file 
on OS/2 

IBMCOBOL 

Specifies an indexed, relative, or serial file associated with a 
VSAM file on OS/2 

MFCOBOL 

Specifies an indexed, relative, or serial file associated with a 
Micro Focus COBOL data file on OS/2 

MQ Specifies a message queue file. 

SEQ Specifies a serial or print file associated with a system 
sequential file for the OS/2 environment. 

/CONTABLE 

Specifies a conversion table name if you want data format conversion 
to be performed on a message. The / CONTABLE entry applies only 
to files where /FILETYPE=MQ. 

If you want data format conversion to be performed on the message, 
specify a conversion table name as shown in the following example: 
/CONTABLE=conversion_tabl e_name 

If a conversion table is specified, VisualAge Generator converts the 
message from local format to remote format when the message is 
added to the queue, and from remote format to local format when the 
message is read from the queue. VisualAge Generator performs 
conversion using the message queue record structure to identify the 
data type of fields in the message. 

Specify EZECONVT for the conversion table name if you want the 
conversion table name to be picked up at run time from the 
EZECONVT special function word. 

/KEYS Specifies the key definition for a BTRIEVE indexed file. This option 
must be specified when the file is created. The definition of a key is 
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separated from the definition of the next key by a colon (:). Each key 
definition contains a starting position and length separated by a plus 
(+). If duplicates are allowed for the key the character d must follow 
the length. The first character position in a record is position 1. 

For example, if the file had a primary key starting in position 1 with a 
length of 4 and a secondary key starting in position 5 with a length of 
20 and you wanted to allow duplicates on the secondary key you 
would specify the following: 
/keys=l+4:5+2Gd 

/NOFF 

Specifies that a form feed should not be issued during Close 
processing for a map. 

/REPLACE or /NOREPLACE 

Specifies whether an existing serial file is replaced by the new one 
that is written by the program. 

You can specify /REPLACE with file type SEQ for the OS/2 
environment. If /REPLACE is specified, the first ADD to a serial file 
in a program, or the first ADD to a serial file following a CLOSE, 
adds the record to the beginning of the file. Previous file contents are 
lost. 

The /REPLACE or /NOREPLACE option is only valid for serial 
(SEQ) files. 

You can use /NOREPLACE to specify that an ADD to a file always 
appendeds to the end of the file. If /NOREPLACE is specified, ADD 
always adds a record to the end of the current file. /NOREPLACE is 
the default. 

/SYSNAME 

Specifies the system name of the file associated with the file name in 
the record. If / FILETYPE=MQ, /SYSNAME specifies the queue 
manager name and queue name. 

The format of the name is system-dependent. If /FILETYPE=MQ, use 
the syntax shown in the following example: 
/SYSW\ME=queue_manager_name:queue_naine 

/SYSTEM 

Specifies the target system affected by this associate command 

You might have multiple associates in one resource association file. 
The resource association used is the first association where the value 
specified for the /SYSTEM option matches the value specified for the 
/SYSTEM generation option value. 

The target system value is OS2. 
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/TEXT Specifies a special type of serial file that contains carriage return and 
line feed (CRLF) characters at the end of each line. When a record is 
read (SCAN), the CRLF characters are automatically removed. When a 
record is written (ADD), the CRLF characters are automatically 
appended to the end of each record. This option is useful when 
exchanging data files with other software packages that expect each 
record to be delimited with the CRLF characters. 

Example of Resource Association File Entries 

Figure 1 shows examples of resource association file entries. 

ASSOCIATE FI LE=FI LEI /SYSTEM=0S2 /FILETYPE=SEQ 

/SYSNAME=MYFILE.DAT 
ASSOCIATE FILE=FILE3 /SYSTEM=0S2 /FILETYPE=MFCOBOL /SYSNAME=I NDXFI LE 
ASSOCIATE FILE=EZEPRINT /FI LETYPE=SEQ /SYSNAME=PRTMAP . OUT 



Figure 1. Examples of Resource Association File Entries 

File Types Supported by Environment and Record Organization 

Table 6 shows the valid file types for the OS / 2environment. 



Table 6. File Types Supported by Environment and Record Organization 







Message 








System 


Indexed 


Queue 


Relative 


Serial 


Print 


OS/2 


IBMCOBOL 


MQ 


IBMCOBOL 


IBMCOBOL 


SEQ 




MFCOBOL 




MFCOBOL 


MFCOBOL 






BTRIEVE 






SEQ 
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Chapter 9. Considerations for C++ SQL Programs in OS/2 



The following sections provide information for preparing and running 
programs that access relational databases: 

• Accessing DB2 Databases 

• Accessing Oracle Databases 

• Accessing Databases Using ODBC 

• Environment Variables 

• Binding an Access Plan 

• Code Page Considerations 

• Static Versus Dynamic SQL Statements 

• Accessing Distributed Databases 

• Oracle for OS/2 Version Considerations 



Accessing DB2 Databases 

VisualAge Generator DB2 support provides direct access to DB2 databases 
without using Datajoiner or ODBC. By specifying the /DBMS=DB2 generation 
option, the VisualAge Generator program is generated specifically for DB2. 
Additional information on using DB2 is documented in the VisualAge 
Generator Design Guide. 



Accessing Oracle Databases 

VisualAge Generator Oracle support provides direct access to Oracle 
databases without using Datajoiner or ODBC. By specifying the 
/DBMS=ORACLE generation option, the VisualAge Generator program is 
generated specifically for Oracle. Additional information on using Oracle is 
documented in the VisualAge Generator Design Guide. 



Accessing Databases Using ODBC 

VisualAge Generator ODBC support provides access to a variety of relational 
databases on OS/2. By specifying the /DBMS=ODBC generation option, the 
VisualAge Generator program is generated specifically for ODBC. A 
VisualAge Generator ODBC program contains dynamic SQL statements as 
opposed to the static SQL statements that are generated for DB2 and Oracle. 
Additional information on using ODBC is documented in the VisualAge 
Generator Design Guide. 
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Environment Variables 

The following environment variables are referenced in preparing and running 

a program containing SQL statements: 

EZERSQLDB 

Specifies the VisualAge Generator Server default database (DB2, 
Oracle, or ODBC). 
FCWDBNAME_<progname> 

Specifies the name of the database (DB2 or Oracle) or the data source 
(ODBC) to be used by a specific VisualAge Generator program. 

Notes: 

1 . For DB2, the name specified is the database alias name. 

2. For Oracle, the name specified must be a service name entry in the 
tnsnames.ora file. 

3. For ODBC, the name specified must be an entry in the odbc.ini 
file. 

EZERSQLDATE 

The value of the EZERSQLDATE environment variable during 
generation determines the DB2 date format generated for the 
precompiler step in the appnameZ.cmd file. The appnameZ.cmd file is 
used to make the program on the OS/2 system. 

For more information on setting environment variables, see "Appendix. 
VisualAge Generator Environment Variables" on page 245. 

Binding An Access Plan Using DB2 

An access plan must be built for each DB2 database a program uses before an 
SQL program can run successfully. The process is called binding the program. 

The access plan is bound during the preparation process to the database used 
during the precompile step. Use the BIND command to bind the program to 
other databases. To use BIND, have the bind file produced during 
preparation, progname. BND, available and issue the following command under 
the DB2 command line processor: 

BIND progname. BND 

Where progname.BND specifies the name of the program you want to run. 

If you do not specify a file name, the messages are directed to the standard 
output. 

To bind an SQL program, you must have the following authority: 
• READ authority to each table the program uses 
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• WRITE authority to each table the program updates 

See your database administrator to get the required authorization. 

Refer to the VisualAge Generator Generation Guide for more information on 
performing binding as part of the program generation and preparation 
process. Refer to the IBM DB2 Command Reference for more information on the 
BIND command. 



Code Page Compatibility 

All SQL programs that use a relational database must use the same code page. 
When you create an SQL database in DB2/2, the code page of the process that 
creates the database is associated with the SQL database. 



Static Versus Dynamic SQL Statements 

When unqualified table names are used in the SQL statements of a VisualAge 
Generator program, the implicit table qualification might be different for static 
mode SQL statements than for dynamic mode SQL statements. 

In static mode, SQL statements are resolved when the program is bound. All 
unqualified SQL table names are qualified with the USERID that is logged on 
to the workstation when the bind takes place. 

In dynamic mode, SQL statements are resolved while the program is running. 
All unqualified SQL table names are qualified with the USERID that is logged 
on to the workstation where the program is running. 

Dynamic mode is used in the following situations: 

• When the Execution Time Statement Build option is specified for SQL 
statements in a generated program 

• When the table name of an SQL row record is defined as a host variable 

For more information on static mode versus dynamic mode, refer to the 

VisualAge Generator Design Guide. 



Accessing Distributed Databases 

The Distributed Database Connection Services/2 licensed program provides 
access to any database manager enabled as a Distributed Remote Database 
Architecture (DRDA) server, including all members of the DB2 product family. 

The DB2 Client Program Enabler/2 licensed program provides access to DB2 
workstation databases, including DB2/2 and DB2/2. DB2 CAE/2 in 
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conjunction with IBM Datajoiner, provides access to non-IBM relational 
databases including Oracle and Sybase databases. 

DDCS/2 and DB2 CAE/ 2 provides the same interface for binding and 
running programs that DB2/2 does. Refer to these products' documentation 
for more information. 



Oracle for OS/2 Version Considerations 

Visual Age Generator Server for OS/2 supports the use of the Oracle7 client 
products only. Oracle8 client software is not available for OS/2. The Oracle7 
client for OS/2 can be used to access both Oracle7 and Oracle8 databases. 
However, when accessing Oracle8 databases using the Oracle7 client, none of 
the Oracle8-specific features (such as parallel execution of the INSERT 
statement) can be used. 

Note: As of this book's printing, according to the Oracle year 2000 

information, the version of SQL*Net as well as the version of the Oracle 
Pro*C C/C++ precompiler shipped with this version of the Oracle for 
OS/2 client software are not year 2000 compliant. Please refer to the 
Oracle product documentation and web site for more information. 
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After the program DLL files have been created, the program is ready to be 
distributed and run on any supported system that has VisualAge Generator 
Server for OS/2 installed. To run your programs, VisualAge Generator 
provides the FCWRUN command with the /R and /NLS options. These 
options are described below. 



FCWRUN Command 

To run a C++ generated and compiled VisualAge Generator MAIN program, 
enter the following command: 
FCWRUN progname 

Where progname is the name of the program. Do not include the .DLL 
extension. 

Note that you can only run MAIN programs in this manner. CALLED 
programs can be run by a call from another VisualAge Generator program or 
a third-generation language (3GL) program. 



Using the /R Option 

Use the /R parameter with the FCWRUN command to specify the name of a 
resource association file. If you do not specify this option, the default filename 
FCW.RSC is used. For example, if the resource association filename is 
PROG1.RSC, and the program name is PROG1, use the following command: 
FCWRUN PR0G1 /R=PR0G1.RSC 

The resource association file can be qualified with a path name. If it is not 
fully qualified, it will be searched for in the following locations: 

1 . The current directory 

2. The directories specified by the FCWDPATH environment variable 

3. The directories specified in the DPATH 

You can also specify the resource association file using the FCWRSC 
environment variable. 
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Using the /NLS Option 

Visual Age Generator provides a /NLS option to specify the language version 
of VisualAge Generator Server you want to use and the program message 
tables to use. To use this option, enter the following command: 
FCWRUN MAINAPP /NLS=xxx 

Where a valid NLS code. 

The following are the valid NLS codes for VisualAge Generator Server: 



Valid Code 


Language 


ENU 


English 


DEU 


German 


DES 


Swiss German 


ESP 


Spanish 


PTB 


Brazilian Portuguese 


KOR 


Korean 


JPN 


Japanese 


CHS 


Simplified Chinese 



If /NLS=xxx is not specified, the environment variable EZERNLS is checked. 
Either /NLS=xxx or EZERNLS must be specified. 



Using Micro Focus COBOL Files with VisualAge Generator C++ Programs 

If you are accessing Micro Focus COBOL files from your VisualAge Generator 
C++ generated programs, the following steps must be performed. 

1 . Link the Micro Focus External File Handler DLL 

i 1 i nk /nof ree extfh+xfhname+cbl dc001,extfh.dl 1 , ,1 cobol+doscal 1 s.extfh.def ; 

Note: EXTFH.OBJ, XFHNAME.OBJ, CBLDC001.OBJ, and LCOBOL.LIB are 
provided with the Micro Focus COBOL Compiler. 

The module definition file EXTFH.DEF contains the following: 

; module definition file for EXTFH under OS/2 

LIBRARY EXTFH INITINSTANCE 

PROTMODE 

DATA NONSHARED 

CODE LOADONCALL 

EXPORTS EXTFH @1 

EXPORTS _MFST0P 02 

2. Place EXTFH.DLL in a directory that is in the LIBPATH environment 
variable. 

3. Specify /FILETYPE=MFCOBOL when creating the Resource Association 
File entry. 
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Calling VisualAge Generator C++ Programs from a 3GL Program 

VisualAge Generator C++ generated programs can call non- VisualAge 
Generator programs written in any third-generation language (3GL) that 
supports the _System calling convention, which is standard for all OS/2 
programs. VisualAge Generator C++ generated programs can also be called by 
non-VisualAge Generator programs written in a 3GL language. The following 
sections describe the various methods possible. The examples provided use 
the C language and are OS/2 specific. CALLVG is the calling program written 
in C and VGAPP is the VisualAge Generator program generated as a C++ 
program. 

Calling a VisualAge Generator CALLED Program Using Dynamic Linking 

1 . Compile and link (prepare) the VisualAge Generator program. 

2. Compile the calling program (callvgl.c) 
ice /C+ /W2 callvgl.c 

3. Link the calling program. 

ilink /nofree callvgl, callvgl.exe, ,os2386,callvgl.def; 

Note: The VisualAge Generator program VGAPP defined the three 
parameters as follows: 

• Parml - Char, 5 bytes 

• Parm2 - Bin, 4 bytes 

• Parm3 - Bin, 4 bytes 

Sample Calling Program Written in C (callvgl.c) 

I '* ****************************************************************** */ 
/* Sample program that calls a VG program using dynamic linking. */ 
/* Character and binary parameters are passed. A binary parameter */ 
/* is returned. */ 

/* ****************************************************************** */ 

#include <os2.h> 
linclude <stdio.h> 

void (* _System vgapp) (char* buffer, int* buflen, int* apprc); 

mainQ 
{ 

HMODULE modHandle; 
CHAR loadError[lGG] ; 
APIRET rc; 

char* string = "vwxyz"; 
int len = 5; 
int apprc = 0; 

/* Load the DLL */ 

rc = DosLoadModul e(l oadError, 

sizeof (loadError) , 

"VGAPP" , 
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SmodHandl e) ; 

if (rc != 0) 

{ 

printf ("DosLoadModule error, rc= %ld", rc) ; 
return; 

} 

/* Get the entry point */ 
rc = DosQueryProcAddr(modHandl e, 
BL. 

"VGAPP", 
(PFN*) &vgapp); 

if (rc != 9) 

{ 

printf ("DosQueryProcAddr error, rc= %ld", rc); 
return; 

} 

vgapp(string, &len, &apprc) ; 

printf ("Return from vgapp, rc = %ld", apprc); 

} 

Sample Module Definition file (callvgl .def) 

NAME CALLVG1 WINDOWCOMPAT 

Calling a VisualAge Generator CALLED Program Using Static Linking 

1 . Compile and link (prepare) the VisualAge Generator program. 

2. Run the IMPLIB utility to create a library file using the dll created in the 
previous step. Library files usually have a .LIB extension. 

implib /N0L0G0 vgapp. lib vgapp.dll 

3. Compile the calling program (callvg2.c). 

ice /C+ /W2 callvg2.c 

4. Link the calling program using the library file created in a previous step to 
resolve the reference to VGAPP. 

ilink /nofree callvg2, callvg2.exe,,vgapp+os2386,callvg2.def; 

Note: The VisualAge Generator program VGAPP defined the three 
parameters as follows: 

• Parml - Char, 5 bytes 

• Parm2 - Bin, 4 bytes 

• Parm3 - Bin, 4 bytes 

Sample Calling Program Written in C (callvg2.c) 

/* ****************************************************************** */ 
/* Sample program that calls a VG program using static linking. */ 
/* Character and binary parameters are passed. A binary parameter */ 
/* is returned. */ 

/* ****************************************************************** */ 
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finclude <stdio.h> 

extern void _System VGAPP(char* buffer, int* buflen, int* rc); 

main() 

{ 

char* string; 
int len; 
int rc; 

string = "abcde"; 
len = 5; 

VGAPP(string, &len, &rc) ; 

printf ("Return from VGAPP, rc = %ld", rc) ; 



Sample Module Definition File (callvg2.def) 

NAME CALLVG2 WINDOWCOMPAT 

Calling a VisualAge Generator MAIN Program from a C program via 
FCWRUN 

1 . Compile and link (prepare) the VisualAge Generator program. 

2. Compile the calling program (callvg3.c) 

ice /C+ /W2 callvg3.c 

3. Link the calling program. 

ilink /nofree callvg3, cal 1 vg3.exe, ,os2386,cal 1 vg3.def; 

Note: Since MAINAPP is a VisualAge Generator MAIN program, it does not 
accept input parameters. 

Sample Calling Program Written in C (callvg3.c) 

I '* ****************************************************************** */ 
/* Sample program that calls a VG main program via FCWRUN. No */ 
/* parameters can be passed using this technique because a VG MAIN */ 
/* program does not accept input parameters. */ 

/* ****************************************************************** */ 

#include <os2.h> 
finclude <stdio.h> 



main() 

{ 

RESULTCODES rescodes; 
char objbuf[40]; 
int rc = 0; 

char* parmstring = "fcwrun.exe\Omainapp\0\0"; 

/* Invoke the VG program via FCWRUN*/ 
rc = DosExecPgm(objbuf , 

sizeof (objbuf) , 

EXECFLAG, 
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parmstri ng, 
NULL, 

Created by ActiveSystems G1/G8/97 Entity not defined.,; 
"fcwrun .exe") ; 

if (rc != 9) 

{ 

printf ("DosExecPgm error, rc= %ld", rc) ; 
return; 

} 

printf ("Return from mainapp\n") ; 

} 

Sample Module Definition File (callvg3.def) 

NAME CALLVG3 WINDOWCOMPAT 



Calling 3GL Programs from a VisualAge Generator C++ Program 

The following describes the technique for calling 3GL programs from a 
VisualAge Generator C++ Program. The example provided uses the C 
language and is OS/2 specific. The 3GL program must be linked as a DLL. If 
you have multiple 3GL programs, you can link them into the same DLL or 
link them individually into their own DLL. If the DLL name and the entry 
point are NOT the same (that is, you have multiple entry points in the DLL), 
then a linkage table must be used when you generate the VisualAge 
Generator program and the DLLNAME and EXTERNALNAME keywords 
must be specified. A sample linkage table entry is provided on page "Sample 
Linkage Table Entry" on page 53. 

1 . Compile and link (prepare) the VisualAge Generator program. 

2. Compile the calling program (nvgapp.c) 
ice /C+ /W2 /Ge- nvgapp.c 

3. Link the calling program. 

ilink /nofree nvgapp, nvgapp.dl 1 , ,os2386,nvgapp.def ; 

Note: The VisualAge Generator MAIN program defined the three parameters 
as follows: 

• Parml - Char, 5 bytes 

• Parm2 - Bin, 4 bytes 

• Parm3 - Bin, 4 bytes 

Sample Called Program written in C (nvgapp.c) 

/ * ********************************** */ 

/* Sample program that is called from a VG program. Character */ 

/* and binary parameters are passed. A binary parameter is returned. */ 

/* ****************************************************************** */ 

linclude <stdio.h> 

extern void _System NVGAPP(char* buffer, int* len, int* rc) ; 
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extern void _System NVGAPP(char* buffer, int* len, int* rc) 
{ 

printf ("Parml = %s\n", buffer); 
printf ("Parm2 = %ld\n", *len); 
printf ("Parm3 = %ld\n", *rc) ; 

*rc = 99; 

} 

Sample Module Definition file (nvgapp.def) 

LIBRARY NVGAPP INITINSTANCE TERMINSTANCE 
PROTMODE 

DATA MULTIPLE NONSHARED READWRITE LOADONCALL 

CODE LOADONCALL 
EXPORTS 
NVGAPP 

Sample Linkage Table Entry 

The following sample linkage table entry would be needed if the sample 
program was not linked as NVGAPP.DLL but as UTIL.DLL. 
:calllink appl name=NVGAPP 1 ibrary=UTIL.DLL external name=NVGAPP 
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Chapter 11. Preparing to Run Java Programs on 
Windows NT 



VisualAge Generator Server for Windows NT enables you to install and run 
Java programs in the Windows NT environment. In order for your programs 
to run in this environment, they must be generated and then prepared. If you 
specified a properties file during generation, specifications from generation 
options parts, resource associations parts and linkage tables were stored in 
that file. You can use this file as is or modify it for use at run time. If you did 
not elect to generate a properties file, you can use the default properties in 
vgj .properties or modify them for use at run time. 

This section contains information needed to prepare a generated Java program 
to run in a Windows NT environment. 

The preparation step is invoked by VisualAge Generator Developer's 
generation facility. You can start preparation by selecting the Start preparation 
command file option in the options notebook, or by specifying the /PREP 
option when you generate from the command line. The PREPARE process can 
be automatically started if the preparation process is being done on the 
generation machine. Otherwise, you must manually start the preparation 
process by running the progname.bat file. If you are generating to another 
Windows NT machine, the /PREP option will only transfer the files. 



Generation Output Files 

The output files created during generation are placed in the generation output 
directory or the current directory if the / GENOUT option is not specified. See 
the VisualAge Generator Generation Guide for a list of these files and how to 
generate them. 



Preparing Your Java Program 

You must prepare your Java programs before they can be run. During 
preparation the program source files are copied to the directory or directories 
specified during generation. 

Your Java programs are generated into one or more Java source files, which 
declare the classes associated with the 4GL program you generated from. 
VisualAge Generator also generates scripts required to FTP the code to 
another Windows NT machine. Properties are loaded when a Java program 
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starts and remain the same for every program that is part of that run unit. A 
run unit is a group of Java programs that make up a transaction. 

There are two methods you can use to prepare your Java generated programs: 

• Use the GENERATE subcommand and have the generator do the prepare. 
This will transfer all parts of the program (programs, UI records, and 
tables) to the target system. 

• Use the PREPARE subcommand. If generation and preparation are being 
done on the same system, the parts will be compiled on that system. 

Preparing Programs Using the Generate Subcommand of the HPTCMD 
Command 

The preparation process is automatically started by generation unless you 
specify the /NOPREP option on the GENERATE command or did not specify 
Start preparation command file in the options notebook. 

Automatic Preparation 

The following options must be specified for preparation to be started on a 
remote Windows NT machine: 

• /DESTHOST=<NThostName> 

• /DESTUID=<NTuserId> 

• /DESTPASSWORD=<NTUserPassword> 

• / DESTDIR=' <NTDirectory> ' 

If you are preparing a Web transaction, specifications for the GatewayServlet 
must be set during generation. See the chapter on generating Web transaction 
programs in the VisualAge Generator Generation Guide. 

Note: The directory must be contained within single quotes and should be the 
full path name. The user must have write authority to the destination 
directory and files. 

Preparing Programs Using the PREPARE Subcommand of the HPTCMD 
Command 

You may choose to run the preparation process independently from the 
generation process. To do this, specify the PREPARE subcommand . 

The PREPARE subcommand can only be issued through the VisualAge 
Generator command line interface. The interactive interface does not support 
the PREPARE subcommand. 

Manual Preparation 

The following options must be specified for preparation to be started on a 
remote Windows NT system: 

• /DESTHOST=<NThostName> 

• /DESTUID=<NTuserId> 
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/ DESTPASSWORD=<NTUserPassword> 
/DESTDIR='<NTDirectory>' 



When you generate and prepare Web transactions that will use a remote 
GatewayServlet, you must set the appropriate access information for the 
system where the gateway code will run. For more information, see the 
chapter on generating Web transactions in the VisualAge Generator Generation 
Guide 

The preparation process on Windows NT transfers the source objects 
(generated source, generated tables, and generated program specific utilities) 
to the target machines. 

To run the program, at a command prompt type the following 
java some. package. PROGNAME 

Where some.package is the name of the package that contains the server 
program and PROGNAME is the name of the program. 

Note: Java is case sensitive and the program will have an uppercase name. 

Compiled Output Files 

The outputs you receive from program generation for use in preparation are 
preparation files and, as specified, a properties file. 

The following files are created for preparation of a Java server program, 
where the program is called progname: 

prognamejs.cmd 

Preparation for program progname 

prognamejsz.bat 

Batch command file that invokes the Java compiler 

prognamelsz.bat 

Batch command file that copies files to the package directory prior to 
compilation of program progname 

prognamejs.ftp 

File transfer protocol control file for program progname 

Properties files 

If you specified that a properties file should be created during generation, by 
default it is named progname. properties, where progname is the name of the 
program. During preparation the properties file is copied to the directory you 
specified for generated server program. 
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You can change settings in the properties files that will alter the way your 
program runs without having to regenerate. You can edit properties files using 
a standard editor. Java is case sensitive so options must be entered with 
correct capitalization. 

Properties files must contain characters that the Java Virtual Machine (JVM) 
can parse. You might need to use some of the following characters in your 
properties files: 

\\ backslash used in paths 

\n new line 

\r carriage return 

\t tab 

To use a character that is not in the machine's native character set, you can 
use UNICODE characters. UNICODE characters consist of a \u followed by 
four hexadecimal digits. 

Comments are permitted and can appear anywhere in the file. Comments 
begin with the characters /* and end with the characters */. 

For more information about specifications set in the properties file, see 

VisualAge Generator Generation Guide. 
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Chapter 12. Customizing Your Workstation to Run Java 
Programs on Windows NT 



This chapter describes the process of setting up the workstation to run Java 
server programs Windows NT. 



Environment Variable Settings 

When you installed VisualAge Generator Server, Java run-time services were 
installed for you as files called hpt.jar and vgjwgs.jar and the environment 
variable CLASSPATH was set to include the path to the directory where these 
files were placed. This directory also contains a vgj. properties file. If you 
created a new properties file, it was copied to this directory when you 
prepared the server program. 

If you want to distribute Java server programs to other Windows NT systems, 
you need to ensure that the environment variables on those systems have 
been set. 

Before you can run your programs, you need to perform the following tasks 
to set up the environment variables for the system: 

• Set up the environment and install the Java Virtual Machine (JVM) 

• Define product-specific environment variables 

• Modify the standard Windows NT-defined variables 

If you want to distribute Java generated programs to other Windows NT 
systems, you also need to set the environment variables on those systems. 

Setting up the environment 

These steps only need to be performed once. They must be done before you 
can run your programs outside VisualAge for Java. 

1 . Install the VisualAge Generator Developer on Java run-time library. This 
library is part of the standard installation of Developer as well as for 
VisualAge Generator Server. You can also install the library separately by 
doing the following: 

• Start the CD product intall. 

• Exit from the first window. 

• Navigate to the directory drive and directory where you installed the 
product. 

• Navigate to the .ADEVJAVA directory and start "IBM VisualAge 
Generator Common Services 4.5. Msi". 
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hpt.jar Contains the VAGen Java run-time code that is necessary 

to run a generated VisualAge for Java program. 

vgjwgs.jar Contains the VAGen Java run- time code that is necessary 
to run a generated VisualAge for Java program. 

vgj .properties Defines the environment settings for the VG Java run-time 
library. It is used in place of environment variables. 

2. Customize vgj. properties as required for your environment. Comments in 
the file describe what effect the properties have on programs as they run. 

3. Install your JVM. 

If you want to run applets, you need a web browser or the appletviewer 
program that comes with the JDK and JRE. 

If you want to run applications, you need a program like java.exe that 
comes with the JDK or jre.exe that comes with the JRE. 

Notes: You need a JVM that runs version 1.2 of Java or higher and a Web 
browser that supports this version. 

Sun's JDK can be downloaded from: 
http://java.sun.eom/products/jdk/l.2 

Sun's JRE can be downloaded from: 
http://java.sun.eom/products/jdk/l.2/jre 

The Web browser you use must support Java version 1.2 or later. 
The most recent version of Netscape and Internet Explorer (IE) 
may support this version of Java. You can also use the Hotjava 
browser instead of Netscape or IE. Hotjava is written in Java and 
will run on any system with Java version 1.1.6 or later installed. 

Hotjava can be downloaded from: 
http://www.javasoft.eom/products/hotjava/i ndex.html 

If you must use Netscape or IE, you can use the Java plug-in that 
is included with the JDK and JRE. Under this configuration, 
instead of the browser running your applet, the plug-in runs it 
using a newer version of the JVM. 

4. If you want to run applications, you need to set your CLASSPATH 
environment variable. 

The CLASSPATH variable is used to tell the JVM running an application 
where the application's code is. CLASSPATH is a list of directories, Jar 
files, and Zip files. 

On Windows, each entry in CLASSPATH is separated by a semicolon. 
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Defining Product-Specific Environment Variables 

VisualAge Generator Server for Windows NT provides environment variables 
that you can add to the Windows NT environment or you can set them from 
the Windows NT command line or Control Panel when setting up your 
environment to run programs. 

For more information on environment variables see "Appendix. VisualAge 
Generator Environment Variables" on page 245 and the VisualAge Generator 
Installation Guide. 



Resource Association Properties 

If the program you are running accesses files, a resource association file must 
be created with an entry for each serial, or message record defined in the 
program. Only sequential files are supported for Java server program I/O 
actions. The resource associations are stored at generation in a properties file 
if you elected to create one. You can also modify your properties file or the 
default properties file (vgj. properties) without regenerating. 

The properties file contains properties that correspond to entries in the 
resource association file. 

Note: There are no corresponding properties for /KEYS and /NOFF because 
they are not supported in Java. /SYSTEM is ignored because Java 
server program generation is only supported for the Windows NT 
environment. 

Resource Associations in Properties Files 

The default properties file is called vgj. properties. For additional information 
on resource associations, see VisualAge Generator Generation Guide. Properties 
that correspond to resource association specifications are shown in the 
following list. In the examples shown here, <filename> is taken from 
"ASSOCIATE FILE=filename" specification in the resource association file. 

vgj.ra.<filename>.filetype 

Specifies the type of the associated file. 

This property is defined in the resource association file by the 
/FILETYPE option. The following values are valid: 

• SEQ specifies a sequential file 

• MQ specifies a message queue. 

In the properties file, a sequential file type specification is shown as: 
vgj . ra . MYFI LE . f i 1 etype=SEQ 

vgj .ra.<filename>. replace 

Specifies whether or not an existing serial file is to be replaced by a 
new one. 
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This property is defined in the resource association file by the 
/REPLACE option.The following values are valid for this property: 

• A value of 1 specifies that a file is to be replaced. 

• A value of 0 specifies that the file is not to be replaced and is the 
default. 

You can use a value of 0 to specify that an ADD to a file always 
appends to the end of the file. 

In the properties file, a replacement specification would be shown as: 
vgj .ra.MYFILE.repl ace=l 

vgj .ra.<f ilenamexsysname 

Specifies the system name of the file associated with the file name in 
the record. 

This property is defined in the resource association file by the 
/SYSNAME option. The format of the name is system and 
type-dependent as shown in the following examples: 

• If the file type is SEQ, vgj.ra.<filename>.sysname specifies the fully 
qualified path and file name. (Slashes in path names are special 
characters that must be escaped using a back slash.) In the 
properties file, a system name for a sequential file would be shown 
as: 

vgj . ra.MYFILE.sysname=c: WdocsWcustomers.txt 

• If the file type is MQ, vgj.ra.<filename>.sysname specifies the queue 
manager name and the queue name. In the properties file, a system 
name specification for a message queue would be shown as: 

vgj . ra . MYFI LE . sysname=queuejnanager_name : queue _name 

vgj .ra.<f ilenamextext 

Specifies a special type of serial file that contains carriage return or 
line feed (CRLF) characters at the end of each line. 

When a record is read (SCAN), the CRLF characters are automatically 
removed. When a record is written (ADD), the CRLF characters are 
automatically appended to the end of each record. This option is 
useful when exchanging data files with other software packages that 
expect each record to be delimited with the CRLF characters. This 
property is defined in the resource association file by the /TEXT 
option. The following values are valid for this property: 

• A value of 1 specifies that the file contains CRLFs. 

• A value of 0 specifies that the file should be read as bytes. 0 is the 
default. 

In the properties file, a text file specification would be shown as: 
vgj.ra.MYFILE.text=l 
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vgj.ra.<filename>.contable 

Specifies the conversion table used when the record data comes from 
a message queue. The following values are valid for this property: 

• * specifies use of the default conversion table. 

• EZECONVT specifies that the file name it contains should be used 
as the conversion table. 

• NONE specifies that no conversion table is used. This property is 
the default. 

In the properties file, a conversion table specification would be shown 
as: 

vgj .ra.MYFILE.contable=EZECONVT 

Example of Resource Associations in a Properties File 

Figure 2 shows an example of a resource association entry in a resource 
association file. 

ASSOCIATE FI LE=FI LEI /SYSTEM=WINNT /FI LETYPE=SEQ 
/SYSNAME=MY FI LE . DAT 

Figure 2. Resource Associations File Entry for a Sequential File 

Figure 3 shows an example of settings from Figure 2 as they would be 
generated into a Java properties file 

vgj . ra. FII_El.fi 1 etype=SEQ 
vg_.ra.FILEl.filetype44YFILE.DAT 

Figure 3. Properties File Entry for a Sequential File 

Figure 4 shows an example of a resource association entry in a resource 
association file. 

ASSOCIATE FI LE=MQV FI LE /SYSTEM=WINNT /FILETYPE=MQ 
/SYSNAME=scott .queue. manager :yel 1 ow. queue 

Figure 4. Resource Associations File Entry for a Message Queue 

Figure 5 shows an example of settings from Figure 4 as they would be 
generated into a Java properties file. 

vgj . ra. MQVFILE.fi 1 etype=MQ 

vgj .ra. FI LEI .sysname=scott . queue. manager :yel 1 ow. queue 
Figure 5. Properties File Entry for a Message Queue 
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Note: The /SYSTEM setting is currently ignored because Java server 
programs are only supported for Windows NT. 

File Types Supported by Environment and Record Organization 

Table 7 shows the valid file types for Java server programs in Windows NT 
environment. 

Table 7. File Types Supported by Environment and Record Organization 



System 


Message Queue 


Serial 


Windows NT 


MQ 


SEQ 
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Chapter 13. Considerations for Java SQL Programs on 
Windows NT 



The following sections provide information on preparing and running 
programs that access relational databases. 



Accessing Relational Databases 

VisualAge Generator Server supports Java server program access of SQL data 
bases through the Java Database Connectivity interface (JDBC). JDBC is a Java 
API that allows Java programs to make dynamic SQL calls to any relational 
database that supports it. 

When you generate Java SQL programs, JDBC is the default selection in the 
DBMS entry field on the generation options window. If you are creating a 
generation options file, you can specify JDBC access to your data by including 
/DBMS=JDBC in your generation options file. You also need to add the 
location of the DBMS-specific JDBC driver class libraries to your CLASSPATH 
environment variable if it was not set by the DBMS during installation. 
Default database connections are specified in your properties file, which 
should also be in a directory referenced by the CLASSPATH environment 
variable. For additional information on using CLASSPATH, see "Chapter 12. 
Customizing Your Workstation to Run Java Programs on Windows NT" on 
page 61. 

When you connect to a JDBC database via EZECONCT, the physical database 
name is resovled by looking up the property vgj . jdbc. database. xxxx, where 
xxxx is the name of the server specified on the EZECONCT call. If this 
property is not defined, the server name specified on the EZECONCT call is 
used 'AS-IS.' 

Most standard database management systems (DB2 and Oracle, for example) 
include the drivers you need to configure your JDBC data access. If you need 
VAGen Java run-time support to load the JDBC drivers, you can specify one 
or more driver names separated by colons via the vgj .jdbc. drivers property. 
VAGen run-time support attempts to locate these specified drivers before 
using JDBC for database access. See the product documentation for the DBMS 
you are using for additional information on configuring data access. 
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Environment Variables 

The CLASSPATH environment variable is referenced in preparing and 
running a program containing SQL statements. CLASSPATH specifies the 
location of the DBMS-specific JDBC driver class libraries. 

For more information on setting environment variables, see "Appendix. 
Visual Age Generator Environment Variables" on page 245. 



Database Default Properties 

The following list summarizes properties that could be specified for use in 
running a Java SQL server program. 

vgj.jdbc.defaultdatabase 

Specifies the default database name to be used for an SQL I/O 
operation if no prior database connection is specified. In a generated 
properties file, this value comes from the SQL database (/SQLDB) 
generation option. 

In the properties file, a default database is specified as follows: 
vgj . jdbc .defaul t .database=empl sdb 

vgj.jdbc.default.database.user.id 

Specifies the default database user ID to be used with the default 
database connection if a default connection is specified. In a generated 
properties file, this value comes from the SQL userid (/SQLID) 
generation option. 

In the properties file, a default database user ID is specified as 
follows: 

vgj .jdbc. defaul t. database. user. id=vguser 

vgj.jdbc.defaulidatabase.user.password 

Specifies the default database user password to be used with the 
default database connection if a default connection is specified. In a 
generated properties file, this value comes from password 
(/SQLPASSWORD) generation option. Use EZECONCT to avoid 
exposing passwords in the properties file. 

In the properties file, a default database password is specified as 
follows: 

vgj .jdbc. defaul t. database. user. id=vgpasswd 
vgj.jdbc.drivers 

Specifies the names of one or more JDBC drivers to be used for JDBC 
access. If multiple drivers are specified, the names should be 
separated by colons. 

In the properties file, a JDBC driver is specified as follows: 
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vgj . jdbc.drivers=C0M.ibm.db2. jdbc.app.DB2Driver 

vgj.jdbc.database.<servername> 

Specifies the name of the JDBC database that is used when a call to 
EZECONCT is made with the specified server name. 

In the properties file, a server name is specified as follows: 
vgj . jdbc. database. DB2SERV=jdbc.db2. sample 

Binding an Access Plan Using DB2 

Because VAGen Java programs use JDBC for database access,, no binding 
process is required. 

Code Page Compatibility 

All SQL programs that use a relational database must use the same code page. 
When you create an SQL database in DB2 for Windows NT, the code page of 
the process that creates the database is associated with the SQL database. 



Static Versus Dynamic SQL Statements 

When unqualified table names are used in the SQL statements of a VisualAge 
Generator program, the implicit table qualification can be different for static 
mode SQL statements and dynamic mode SQL statements. 

In static mode, SQL statements are resolved when the program is bound. All 
unqualified SQL table names are qualified with the USERID that is logged on 
to the workstation when the bind takes place. 

In dynamic mode, SQL statements are resolved while the program is running. 
All unqualified SQL table names are qualified with the USERID that is logged 
on to the workstation where the program is running. 

Dynamic mode is used in the following situations: 

• When the Execution Time Statement Build option is specified for SQL 
statements in a generated program 

• When the table name of an SQL row record is defined as a host variable 

Note: Because database access via JDBC is done through dynamic calls, all 
unqualified table names used in the SQL statements of VAGen 
programs are resolved dynamically. 

For more information on static mode versus dynamic mode, refer to the 

VisualAge Generator Design Guide. 
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Accessing Distributed Databases 

The Distributed Database Connection Services for Windows NT licensed 
program provides access to any database manager enabled as a Distributed 
Remote Database Architecture (DRDA) server, including all members of the 
DB2 product family. 

The DB2 Client Program Enabler for Windows NT licensed program provides 
access to DB2 workstation databases, including DB2 and DB2 CAE for 
Windows NT in conjunction with IBM Datajoiner, provides access to non-IBM 
relational databases including Oracle and Sybase databases. 

DDCS for Windows NT and DB2 CAE for Windows NT provides the same 
interface for binding and running programs that DB2 does. Refer to these 
products' documentation for more information. 
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Chapter 14. Running Java Programs on Windows NT 



After the preparation files have generated have been generated and the 
properties file has been generated or updated and placed in a directory 
specified in the CLASSPATH, the program is ready to be distributed and run 
on any supported system that has VisualAge Generator Server for 
Windows NT installed. 



Running the program 

To run a Java server program, from a command prompt, type the following 
command: 

java some. package. progname 

Where java is the default command used to start the JVM, some.package is the 
name of the package you generated the program into, and progname is the 
name of the server program itself. 

Because the Java virtual machine finds classes using the CLASSPATH 
environment variable, which directories you can run the server program from 
is determined by the paths you specify for that variable. If your server 
program is stored in a .ZIP or JAR (Java archive) file, you must specify the 
fully qualified path and the .ZIP or JAR file name in the CLASSPATH. 

If the server program is not in a jar or zip, the class should be in a directory 
tree that is structured according to the package name. Then there are two 
ways to run the program depending on how you specify the path in 
CLASSPATH. For example, if your class is in a package named 
some.package.progname, you could put it in 
c:\my\cl asses\some\package 

If you add the directory c:\my\classes to your CLASSPATH (as shown in the 
example), you can run the program from any directory. 

C :\IBMConnectors\cl asses ;C:\IBMVAGEN\VGCS045\hpt. jar ; C:\my\cl asses 

If you just put a dot (meaning the current directory) in your CLASSPATH (as 
shown in the example), you can only run the program after you cd to 
c:\my\classes. 

C:\IBMConnectors\cl asses ;C:\IBMVAGEN\VGCS045\;C:\IBMVAGEN\VGCS045\hpt. jar;. 
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Note that you can only run MAIN programs in this manner. CALLED 
programs can be run by a call from another VisualAge Generator program or 
a third-generation language (3GL) program. 

Specifying Other Properties Files 

By default the properties file used at runtime is the progname. properties file, 
where progname is the name of the generated Java program. If that file is not 
found in the directory specified in the CLASSPATH environment variable or 
the local directory, vgj. properties is used. 

If both of these files are found, then both files are used, but values in the 
progname. properties file override any that are also specified in vgj. properties. 

If you want to use another properties file you can do so from the command 
line using vgj. properties. file as shown here. 

vgj.properties.file 

Specifies an alternate properties file to be used at runtime. 

From the command line, an alternate properties file is specified as 
follows: 

java -Dvg j . propert i es . f i 1 e=c : \ j i\ia\alternatename . properti es 

Here, the value for vgj.properties.file includes the fully qualified path 
to the alternate properties file. 

Starting the JVM 

Although the default command for starting a JVM is java, in the properties 
file you can define a different command to start a new JVM. You should use 
this property when you start a program using a CREATX statement. 

vgj . j ava. command 

Specifies an alternate command to be used at runtime. 

In the properties file, an alternate properties file is specified as 
follows: 

vgj . java.command=jre 

You can also use this property to specify both a different start 
command and a different properties file-D. 

vgj . java.command=jre -Dvg j .properties.fi 1 e=c:\\j&va\\alternatename . properties 
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NLS Properties 

Properties from options affecting which language version of VisualAge 
Generator Server for Windows NT and the program message tables are used 
can also be specified in the properties files. When a propgram is generated the 
NLS code is picked up from generation options. The date format is picked up 
from user preferences 

vgj.nls.code 

Specifies the language to be used at runtime. In a generated properties 
file, this value comes from the Target NLS (/TARGNLS) generation 
option. 

In the properties file, the target national language property is specified 

as follows: 

vgj .nl s .code=ENU 

vgj.datemask.<format>.<length>.<NLS> 

Specifies the format and language for dates used at runtime. Here, 
length and format are determined by user-specified settings in options 
or preferences. NLS is the code defined by the Target NLS 
(/TARGNLS) generation option. 

In the properties file, an example of a date format and language 
property is: 

vgj .datemask.gregon'an.long.ENU 

Note: Gregorian and juilan long formats are supported. 
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Part 4. Running VisualAge Generator C++ programs 
Windows NT 
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Chapter 15. Preparing to Run C++ Programs on 
Windows NT 



VisualAge Generator Server for Windows NT enables you to install and run 
C++ programs in the Windows NT environment. In order for your programs 
to run in this environment, they must be generated and then prepared. 

This section contains information needed to prepare a generated C++ program 
to run in an Windows NT environment. During generation, output files are 
created that are used for program preparation. These files are used when 
preparing your programs. 

The preparation step is invoked by VisualAge Generator Developer's 
generation facility. You can start preparation by selecting the Start preparation 
command file option in the options notebook, or by specifying the /PREP 
option when you generate from the command line. The PREPARE process can 
be automatically started if the preparation process is being done on the 
generation machine. Otherwise, you must manually start the preparation 
process by running the appnameZ.bat file. If you are generating to another 
machine, the /PREP option will only transfer the files. 



Generation Output Files 

The output files created during generation are placed in the generation output 
directory or the current directory if the / GENOUT option is not specified. See 
the VisualAge Generator Generation Guide for a list of these files and how to 
generate them. 

Preparing Your C++ Program 

You must prepare your C++ programs before they can be run. The 
preparation step compiles the program and map source files into executable 
DLLs. 

Your C++ programs are compiled using either the VisualAge for C++ 
Compiler for Windows NT or Microsoft Visual C++ Compiler. The 
preparation step also uses the nmake utility that comes with both compilers. 
Nmake accepts as input a makefile which lists the source code and 
instructions for compiling and linking this source code. VisualAge Generator 
Server for Windows NT provides a makefile called FCWMAKE that contains 
instructions on how to compile the generated programs. 
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There are two methods you can use to prepare your C++ generated programs: 

• Use the GENERATE subcommand and have the generator do the prepare. 
This will transfer all parts of the program (programs, map groups, and 
tables) to the target system. 

• Use the PREPARE subcommand. If generation and preparation are being 
done on the same system, the parts will be compiled and linked. 

Preparing Programs Using the Generate Subcommand of the HPTCMD 
Command 

The preparation process is automatically started by generation unless you 
specify the /NOPREP option on the GENERATE command or did not specify 
Start preparation command file in the options notebook. 

Automatic Preparation 

The following options must be specified for preparation to be started on a 
remote Windows NT machine: 

• /DBUSER=<NTdatabaseUserid> 

• /DBPASSWORD=<NTdatabasePassword> 

• /DESTHOST=<NThostName> 

• /DESTUID=<NTuserId> 

• /DESTPASSWORD=<NTUserPassword> 

• / DESTDIR=' <NTDirectory> ' 

Note: The directory must be contained within single quotes and should be the 
full path name. The user must have write authority to the destination 
directory and files. 

If you choose this method to do your preparation, be sure that the 
FCWMAKE environment variable contains the name of the directory where 
the Visual Age Generator Server for Windows NT product was installed. This 
environment variable is set in the Windows NT environment, if you chose to 
have it updated during installation, or set it manually using the Control 
Panel. 

Preparing Programs Using the PREPARE Subcommand of the HPTCMD 
Command 

You may choose to run the preparation process independently from the 
generation process. To do this, specify the PREPARE subcommand . 

The PREPARE subcommand can only be issued through the VisualAge 
Generator command line interface. The interactive interface does not support 
the PREPARE subcommand. 

Manual Preparation 

The following options must be specified for preparation to be started on a 
remote Windows NT system: 
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• /DBUSER=<NTdatabaseUserid> 

• / DBPASSWORD=<NTdatabasePassword> 

• / DESTHOST=<NThostName> 

• /DESTUID=<NTuserId> 

• /DESTPASSWORD=<NTUserPassword> 

• /DESTDIR='<NTDirectory>' 

The preparation process on Windows NT transfers the source objects 
(generated source, generated tables, and generated program specific utilities) 
to the target machine. After the program has been compiled and linked using 
the prognameZ.bat file, it can then be run using the fcwrun command: 
fcwrun progname 

Where progname is the name of the program. 



Compiled Output Files 

The outputs you receive from program preparation are dynamic link libraries 
(DLLs) which, along with the .TAB files for tables, constitute the executable 
code for the program. The following DLLs are created for each program: 

progname.DLL 

progname is the name of the program 

map. DLL 

map is the name of the main map group 
hlp.DLL 

hip is the name of the help map group 

The map. DLL and hlp.DLL are created only if a map group or help map 
group is defined for the program. 

In addition to the DLL output files, you will receive other files with 
extensions such as OBJ, DEF, MAP, SQC, BND. The .BND file should be saved 
in case the program is moved to another system so that the DB2 program 
package can be bound into the database on that system. All the other files are 
temporary files and can be deleted. 



Storing Program DLLs 

The compiled program DLLs you received at compilation time need to be 
placed in a directory specified in the PATH environment variable in your 
Windows NT environment. You can also set this up through your Control 
Panel in Windows NT. The .TAB files need to be placed in a directory 
specified in the FCWDPATH or PATH environment variable. 
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Chapter 16. Customizing Your Workstation to Run C++ 
Programs on Windows NT 



This chapter describes the process of setting up the workstation to run 
Windows NT programs. Customization of the workstation includes the 
following: 

• Setting environment variables 

• Creating a resource association file 



Environment Variable Settings 

Before you can run your programs, you need to perform the following tasks 
to set up the environment variables for the system: 

• Define product-specific environment variables 

• Modify the standard Windows NT-defined variables 

If you want to distribute C++ generated programs to other Windows NT 
systems, you also need to set the environment variables on those systems. 

Defining Product-Specific Environment Variables 

VisualAge Generator Server for Windows NT provides environment variables 
that you can add to the Windows NT environment or you can set them from 
the Windows NT command line or Control Panel when setting up your 
environment to run programs. 

Table 8 shows the product-specific environment variables used with generated 
Windows NT C++ programs. 



Table 8. Product Specific Environment Variables for VisualAge Generator Server for 
Windows NT and Common Services 

Environment variable Runtime services Common services 



CSOTROPT 




Optional 


CSOTROUT 




Optional 


DB2INSTANCE 


Optional 




EZERJULS_xxx 


Optional 




EZERJULL_xxx 


Optional 




EZERGRGS_xxx 


Optional 




EZERGRGL_xxx 


Optional 





EZERNLS Required Optional 
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Table 8. Product Specific Environment Variables for VisualAge Generator Server for 
Windows NT and Common Services (continued) 

Environment variable Runtime services Common services 



EZERSQLDB 


Optional 


FCWCOMP 


Required 


FCWDBNAME_<proj 


;name> Optional 


FCWDBPASSWORD 


Optional 


FCWDBUSER 


Optional 


FCWDBVERSION 


Optional 


FCWDPATH 


Required 


FCWMAKE 


Required 


FCWRSC 


Optional 


FCWOPT 


Optional 


FCWTROPT 


Optional 



FCWTROUT Optional 



A typical environment might contain the following: 

CSODIR=E:\HPTCSOW 

CS0TR0PT=2 

EZERNLS=ENU 

EZERSQLDB=SAMPLE 

FCE0PT=1 

FCETR0PT=11 

FCWCOMP=VAC++ 

FCWDBCS=NO 

FCWDBNAME=SAMPLE 

FCWDBVERSI0N=8 

FCWDPATH=C:\VGSERVW 

FCWMAKE=C:\VGSERVW 

FCWTR0PT=31 

FCWTROUT=FCWTRACE.OUT 

INCLUDE=C:\VGSERVW\INCLUDE;C:\HPTCSOW\INCLUDE;%INCLUDE% 

LIB=C:\VGSERVW\LIB;C:\HPTCSOW\LIB;%LIB% 

PATH=C:\GENOUT;C:\VGSERVW;C:\HPTCSOW;%PATH% 



In addition, the value of EZERSQLDATE is used during generation to set the 
DB2 date and time format specified in the SQL preparation commands in 
prognameZ.BAT, the preparation command file created at this time. 

For more information on environment variables see "Appendix. VisualAge 
Generator Environment Variables" on page 245 and the VisualAge Generator 
Installation Guide. 
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Modifying the Standard Windows NT-Defined Variables 

Your PATH statement should contain the directory where the program DLLs 
are stored. This directory is usually the generation output directory. 

Table 9 shows the standard environment variables used with generated 
Windows NT C++ programs. 

Table 9. Standard Environment Variables for VisualAge Generator Server for 
Windows NT and Common Services 

Environment variable Runtime services Common services 

HELP 

PATH Required Required 



Resource Association File 

If the program you are running accesses files, a resource association file must 
be created with an entry for each serial, indexed, message queue or relative 
record defined in the program. The resource association file is also used when 
your program contains printer maps and you want the output directed to a 
file instead of the default output device (for example LPT1). In the 
Windows NT environment, VisualAge Generator Server for Windows NT 
reads the resource association file at run time, not at generation time. 

Creating Resource Association Files 

You can create and edit resource association files using a standard editor. You 
can enter options and values in uppercase or lowercase. All of the options can 
span lines. A period at the end of each entry is optional. 

Comments are permitted and can appear anywhere in the file. Comments 
begin with the characters /* and end with the characters */. 

The default resource association file is called FCW.RSC. If you create a new 
resource association file, you can override the default and specify the new file 
by using the /R parameter at run time or by specifying a file name in the 
FCWRSC environment variable. For more information on using the /R option, 
see the "Chapter 18. Running C++ Programs on Windows NT" on page 95. 

Note: If your program does file I/O, a resource association file is required. If 
you want to redirect the output from a printer map, specify an entry 
for EZEPRINT: 

ASSOCIATE FI LE=EZEPRINT /SYSNAME=d : \output\report . out 

/FILETYPE=SEQ 

The following diagram shows the syntax of the entries in the resource 
association file. 
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►►—ASSOCIATE— FILE=/z lename- 



rx 



■/FILETYPE=- r BTRIEVE- 



■/CONTABLE- 



-IBMCOBOL- 

-MQ 

-SEQ 



i— /NOREPLACE — , 



L/ KEYS J L/noffJ 



■/REPLACE- 



■/SYSNAME=sysfem 



resource name' 



/SYSTEM=torget system- 



^ L/textJ 



ASSOCIATE 

Associates the file name specified in a record definition or the printer 
file with the physical file that is used for the record at run time 

FILE Specifies the file name in the record for which you are defining 
system resource association information 

The file name can be EZEPRINT (the print file for the program) or 
one of the file names specified for a serial or indexed record used by 
the program. 

/FILETYPE 

Specifies the implementation of the file in a target environment 

The valid file types are system-dependent. Table 10 on page 86 shows 
the valid file types for the Windows NT environment. 

The file type can be one of the following: 

BTRIEVE 

Specifies an indexed or serial file associated with a BTRIEVE 
file on Windows NT. 

IBMCOBOL 

Specifies an indexed file associated with a local VSAM file on 
Windows NT. 

MQ Specifies a message queue file. 

SEQ Specifies a serial or print file associated with a system 
sequential file for the Windows NT environment. 

/CONTABLE 

Specifies a conversion table name if you want data format conversion 
to be performed on a message. The / CONTABLE entry applies only 
to files where /FILETYPE=MQ. 
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If you want data format conversion to be performed on the message, 
specify a conversion table name as shown in the following example: 
/CONTABLE=conversi on_tabl e_name 

If a conversion table is specified, VisualAge Generator converts the 
message from local format to remote format when the message is 
added to the queue, and from remote format to local format when the 
message is read from the queue. VisualAge Generator performs 
conversion using the message queue record structure to identify the 
data type of fields in the message. 

Specify EZECONVT for the conversion table name if you want the 
conversion table name to be picked up at run time from the 
EZECONVT special function word. 

/KEYS Specifies the key definition for a BTRIEVE indexed file. This option 
must be specified when the file is created. The definition of a key is 
separated from the definition of the next key by a colon (:). Each key 
definition contains a starting position and length separated by a plus 
(+). If duplicates are allowed for the key, the character d must follow 
the length. The first character position in a record is position 1. 

For example, if the file had a primary key starting in position 1 with a 
length of 4 and a secondary key starting in position 5 with a length of 
20 and you wanted to allow duplicates on the secondary key, you 
would specify the following: 
/keys=l+4:5+2Gd 

/NOFF 

Specifies that a form feed should not be issued during Close 
processing for a map. 

/REPLACE or /NOREPLACE 

Specifies whether an existing serial file is replaced by the new one 
that is written by the program. 

You can specify /REPLACE with file type SEQ for the Windows NT 
environment. If /REPLACE is specified, the first ADD to a serial file 
in a program, or the first ADD to a serial file following a CLOSE, 
adds the record to the beginning of the file. Previous file contents are 
lost. 

The /REPLACE or /NOREPLACE option is only valid for serial 
(SEQ) files. 

You can use /NOREPLACE to specify that an ADD to a file always 
appends to the end of the file. If /NOREPLACE is specified, ADD 
always adds a record to the end of the current file. /NOREPLACE is 
the default. 
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/SYSNAME 

Specifies the system name of the file associated with the file name in 
the record. If / FILETYPE=MQ, /SYSNAME specifies the queue 
manager name and queue name. 

The format of the name is system-dependent. If /FILETYPE=MQ, use 
the syntax shown in the following example: 
/SYSW\ME=queue_manager_name:queue_name 

/SYSTEM 

Specifies the target system affected by this associate command. 

You might have multiple associates in one resource association file. 
The resource association used is the first association where the value 
specified for the /SYSTEM option matches the value specified for the 
/SYSTEM generation option value. 

The target system value is WINNT. 

/TEXT Specifies a special type of serial file that contains carriage return or 
line feed (CRLF) characters at the end of each line. When a record is 
read (SCAN), the CRLF characters are automatically removed. When a 
record is written (ADD), the CRLF characters are automatically 
appended to the end of each record. This option is useful when 
exchanging data files with other software packages that expect each 
record to be delimited with the CRLF characters. 

Example of Resource Association File Entries 

Figure 6 shows examples of resource association file entries. 

ASSOCIATE FI LE= FI LEI /SYSTEM=WINNT /FI LETYPE=SEQ 

/SYSNAME=MYFILE.DAT 
ASSOCIATE FI LE=FI LE3 /SYSTEM=WINNT /FI LETYPE=BTRI EVE /SYSNAME=INDXFI LE 
ASSOCIATE FI LE=EZEPRINT /FI LETYPE=SEQ /SYSNAME=PRTMAP.OUT 

Figure 6. Examples of Resource Association File Entries 

File Types Supported by Environment and Record Organization 

Table 10 shows the valid file types for the Windows NT environment. 



Table 10. File Types Supported by Environment and Record Organization 



System 


Indexed 


Message 
Queue 


Relative 


Serial 


Print 


Windows NT 


BTRIEVE 

IBMCOBOL 

VSAM 


MQ 




BTRIEVE 
SEQ VSAM 


SEQ 
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Chapter 17. Considerations for C++ SQL Programs on 
Windows NT 



The following sections provide information for preparing and running 
programs that access relational databases: 

• Accessing DB2 Databases 

• Accessing Oracle Databases 

• Accessing Databases Using ODBC 

• Environment Variables 

• Binding an Access Plan Using DB2 

• Code Page Considerations 

• Static Versus Dynamic SQL Statements 

• Accessing Distributed Databases 

• Oracle for Windows NT Version Considerations 

• Migrating Applications from Oracle 7 to Oracle 8 



Accessing DB2 Databases 

VisualAge Generator DB2 support provides direct access to DB2 databases 
without using Datajoiner or ODBC. By specifying the /DBMS=DB2 generation 
option, the VisualAge Generator program is generated specifically for DB2. 
Additional information on using DB2 is documented in the VisualAge 
Generator Design Guide. 



Accessing Oracle Databases 

VisualAge Generator Oracle support provides direct access to Oracle 
databases without using Datajoiner or ODBC. By specifying the 
/DBMS=ORACLE generation option, the VisualAge Generator program is 
generated specifically for Oracle. Additional information on using Oracle is 
documented in the VisualAge Generator Design Guide. 



Accessing Databases Using ODBC 

VisualAge Generator ODBC support provides access to a variety of relational 
databases on Windows NT. By specifying the /DBMS=ODBC generation 
option, the VisualAge Generator program is generated specifically for ODBC. 
A VisualAge Generator ODBC program contains dynamic SQL statements as 
opposed to the static SQL statements that are generated for DB2 and Oracle. 
Additional information on using ODBC is documented in the VisualAge 
Generator Design Guide. 
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Environment Variables 



The following environment variables are referenced in preparing and running 

a program containing SQL statements: 

DB2INSTANCE 

Specifies the name of the DB2 instance. (Applies to DB2 only.) 
EZERSQLDB 

Specifies the VisualAge Generator Server default database (DB2, 
Oracle, or ODBC). 
FCWDBNAME_<progname> 

Specifies the name of the database (DB2 or Oracle) or the data source 
(ODBC) to be used by a specific VisualAge Generator program. 

Notes: 

1 . For DB2, the name specified is the database alias name. 

2. For Oracle, the name specified must be a service name entry in the 
tnsnames.ora file. 

3. For ODBC, the name specified must be an entry in the odbc.ini 
file. 

FCWDBVERSION 

Specifies the version of the database software installed on the 
Windows NT system. The value of FCWDBVERSION is used when 
preparing SQL programs for execution under Windows NT. 

Notes: 

1 . For DB2, this value is not used. 

2. For Oracle, supported values are 7 and 8. 

3. For ODBC, this value is not used. 
EZERSQLDATE 

The value of the EZERSQLDATE environment variable during 
generation determines the DB2 date format generated for the 
precompiler step in the appnameZ.bat file. The appnameZ.bat file is 
used to make the program on the Windows NT system. 

For more information on setting environment variables, see "Appendix. 
VisualAge Generator Environment Variables" on page 245. 

Binding An Access Plan Using DB2 

An access plan must be built for each DB2 database a program uses before an 
SQL program can run successfully. The process is called binding the program. 

The access plan is bound during the preparation process to the database used 
during the precompile step. Use the BIND command to bind the program to 
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other databases. To use BIND, have the bind file produced during 
preparation, progname.BNT), available and issue the following command under 
the DB2 command line processor: 

BIND progname . BND 

Where progname. BND specifies the name of the program you want to run. 

To bind an SQL program, you must have the following authority: 

• READ authority to each table the program uses 

• WRITE authority to each table the program updates 

See your database administrator to get the required authorization. 

Refer to the VisualAge Generator Generation Guide for more information on 
performing binding as part of the program generation and preparation 
process. Refer to the IBM DB2 Command Reference for more information on the 
BIND command. 



Code Page Compatibility 

All SQL programs that use a relational database must use the same code page. 
When you create an SQL database in DB2 for Windows NT, the code page of 
the process that creates the database is associated with the SQL database. 



Static Versus Dynamic SQL Statements 

When unqualified table names are used in the SQL statements of a VisualAge 
Generator program, the implicit table qualification can be different for static 
mode SQL statements and dynamic mode SQL statements. 

In static mode, SQL statements are resolved when the program is bound. All 
unqualified SQL table names are qualified with the USERID that is logged on 
to the workstation when the bind takes place. 

In dynamic mode, SQL statements are resolved while the program is running. 
All unqualified SQL table names are qualified with the USERID that is logged 
on to the workstation where the program is running. 

Dynamic mode is used in the following situations: 

• When the Execution Time Statement Build option is specified for SQL 
statements in a generated program 

• When the table name of an SQL row record is defined as a host variable 

For more information on static mode versus dynamic mode, refer to the 

VisualAge Generator Design Guide. 
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Accessing Distributed Databases 

The Distributed Database Connection Services for Windows NT licensed 
program provides access to any database manager enabled as a Distributed 
Remote Database Architecture (DRDA) server, including all members of the 
DB2 product family. 

The DB2 Client Program Enabler for Windows NT licensed program provides 
access to DB2 workstation databases, including DB2 and DB2 CAE for 
Windows NT in conjunction with IBM Datajoiner, provides access to non-IBM 
relational databases including Oracle and Sybase databases. 

DDCS for Windows NT and DB2 CAE for Windows NT provides the same 
interface for binding and running programs that DB2 does. Refer to these 
products' documentation for more information. 



Oracle for Windows NT Version Considerations 

VisualAge Generator Server for Windows NT ships support for both the 
Oracle7 and Oracle8 client products and can be configured to use either one. 
The Oracle8 client is used by default. The Oracle7 and Oracle8 clients cannot 
be used simultaneously. For example, you cannot use the Oracle7 client for 
one application and the Oracle8 client for another without reconfiguring 
VisualAge Generator Server for Windows NT in between. 

A VisualAge Generator Server tool called orasetup is provided that allows 
you to configure the version of the Oracle client that VisualAge Generator 
Server should use. The orasetup tool is located in the \samples directory of 
the VisualAge Generator Server for Windows NT product installation 
directory (for example, c:\vgservw\samples). 

Note: If you want to use Oracle8i, see the orasetup readme orasetup. readme, 
on the product CD for additional information. 

To invoke the orasetup tool, issue the orasetup command from a command 
window within the product installation directory. The syntax is as follows: 
orasetup [ -i 7 | S ] [ -o 7 | 8 ] [ -csodir directory ] [ -fcwdir directory ] [-h|H|?] 

where 

-i Specifies the version of Oracle to change to. The default is 7. 

-o Specifies the current version of the Oracle client in use by VisualAge 
Generator Server for Windows NT. 

If no value is specified for this option, the value of the 
FCWDBVERSION environment variable is used. 
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Note: The value of FCWDBVERSION is maintained using the 

orasetup tool. You should never need to manually set the value 
of FCWDBVERSION. 



-csodir 

Specifies the product installation directory for VisualAge Generator 
Common Services. The default is c:\hptcsow. 

-fcwdir 

Specifies the VisualAge Generator Server product installation 
directory. The default is c:\vgservw. 

-h I H I ? 

Displays help information for the orasetup tool. 

A slash ( / ) can be used in place of the dash ( - ) when specifying orasetup 
options. 

Note: To issue the orasetup command from any command line, you must 
manually add the samples subdirectory of the product installation 
directory to your Windows NT PATH environment variable (for 
example, c:\vgservw\samples). 

When the values specified for -o and -i are different, orasetup does the 
following: 

• Swaps the current version of fcworcl.dll and csoora.dll for the specified 
version. 

• Updates the value of FCWDBVERSION in the Windows NT Registry. 

If the value of FCWDBVERSION ever becomes inconsistent with the current 
state of VisualAge Generator Server, you can determine the correct value by 
checking the \DLL directory of the VisualAge Generator Server product 
installation directory for the version of the Oracle modules that are not 
currently being used. For example, if the files fcworcl7.dll and csoora7.dll 
exist in this directory, Oracle7 is not currently being used by VisualAge 
Generator Server. Hence, the current version of the Oracle client being used is 
version 8, and you should set FCWDBVERSION to 8. 

Note: The orasetup tool cannot update the value of FCWDBVERSION in any 
open command window or in any running applications. For orasetup 
changes to take effect, you must open new command windows and 
restart any running applications. 

For more information about the orasetup tool, see the orasetup.readme file in 
the \ samples directory of the VisualAge Generator Server for Windows NT 
product installation directory or issue the command orasetup -h. 
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Migrating Applications from Oracle 7 to Oracle 8 

If you have migrated from the Oracle7 for Windows NT client to the Oracle8 
for Windows NT client on your Windows NT system, three migration paths 
are available for upgrading your VisualAge Generator applications that use 
the Oracle7 client library to use of the Oracle8 client library. 

Note: If you want to use Oracle8i, see the orarelink readme 

orarel ink. readme, on the product CD for additional information. 

Choose one of the following paths, depending upon the Oracle8 client /server 
features you plan on using: 

• If you do not want to use any of the new Oracle8 features, do nothing at 
all. The Oracle7 client library is provided with the Oracle8 client for 
compatibility. You can use your existing VisualAge Generator Oracle7 
applications to access both Oracle7 and Oracle8 databases without any 
modifications. However, when accessing Oracle8 databases through an 
Oracle7 client, none of the Oracle8-specific features (such as parallel 
execution of the INSERT statment) can be used. In this case, you will 
conceptually still be making Oracle7 connections. 

• If you want to use new Oracle8 features that do not require recoding of the 
application, relink your VisualAge Generator Oracle7 applications with the 
Oracle8 client library. This allows you to take advantage of Oracle8 features 
such as Improved Data Warehouse Performance. 

A batch file is provided with VisualAge Generator to help automate the 
relink process. The file is called orarelink.bat and is located in the \samples 
directory of your VisualAge Generator Server for Windows NT product 
installation directory. 

The orarelink command syntax is as follows: 
orarelink [/h|H[?] appnamel appname2 ... 

where 

appnamel appnamel ... 

Specify the names of applications (separated by a blank space) that 
you would like to relink. 

h I HI ? 

Displays help information for the orarelink command. 

Notes: 

- You can only specify applications that are in the current directory from 
which you issue the orarelink command. 
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- To issue the orarelink command from any command line, you must 
manually add the samples subdirectory of the product installation 
directory to your Windows NT PATH environment variable (for 
example, c:\vgservw\samples). 

- The appname parameters are application names, not the names of the 
z.bat files. For example, to relink a VisualAge Generator application 
named TEST1, you would issue the command orarelink TEST1. 

• If you want to use new Oracle8 features that require recoding of the 
application, you must recode your VisualAge Generator applications. 
Recoding allows you to take advantage of Oracle8 features such as the 
Object Relational Technology. You must also regenerate and prepare any 
VisualAge Generator applications that you recode. 

Notes: 

• Oracle8 databases can be accessed using VisualAge Generator Oracle7 
applications. If you continue to use the Oracle7 client, no changes are 
necessary. Similarly, Oracle7 databases can be accessed using VisualAge 
Generator Oracle8 applications as long as the clients do not use any of the 
Object Relational Technology features of Oracle8. 

• If you have applications that you have precompiled with the Oracle8 
precompiler, you cannot relink those applications with the Oracle7 client 
SQL library. The precompiler output is not backward compatible. However, 
applications that have been precompiled with the Oracle7 precompiler can 
be relinked with the Oracle8 client SQL library. 

For more information on migrating existing Oracle7 precompiler applications 
to Oracle8 precompiler applications, refer to the documentation that came 
with your copy of the Oracle8 for Windows NT client. For more information 
about the orarelink tool, see the orarelink.readme file in the \samples 
directory of the VisualAge Generator Server for Windows NT product 
installation directory or issue the command orarelink /h. 
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Chapter 18. Running C++ Programs on Windows NT 



After the program DLL files have been created, the program is ready to be 
distributed and run on any supported system that has VisualAge Generator 
Server for Windows NT installed. To run your programs, VisualAge 
Generator provides the FCWRUN command with the /R and /NLS options. 
These options are described below. 



FCWRUN Command 

To run a C++ generated and compiled VisualAge Generator MAIN program, 
enter the following command: 
fcwrun progname 

Where progname is the name of the program. Do not include the .DLL 
extension. 

Note that you can only run MAIN programs in this manner. CALLED 
programs can be run by a call from another VisualAge Generator program or 
a third-generation language (3GL) program. 



Using the /R Option 

Use the /R parameter with the FCWRUN command to specify the name of a 
resource association file. If you do not specify this option, the default filename 
FCW.RSC is used. For example, if the resource association filename is 
PROG1.RSC, and the program name is PROG1, use the following command: 
FCWRUN PR0G1 /R=PR0G1.RSC 

The resource association file can be qualified with a path name. If it is not 
fully qualified, it will be searched for in the following locations: 

1 . The current directory 

2. The directories specified by the FCWDPATH environment variable 

3. The directories specified in the PATH 

You can also specify the resource association file using the FCWRSC 
environment variable. 
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Using the /NLS Option 

Visual Age Generator provides a /NLS option to specify the language version 
of VisualAge Generator Server for Windows NT you want to use and the 
program message tables to use. To use this option, enter the following 
command: 

FCWRUN MAINAPP /NLS=xxx 

Where a valid NLS code. 

The following are the valid NLS codes for VisualAge Generator Server for 



Windows NT: 




Valid Code 


Language 


ENU 


English 


DEU 


German 


DES 


Swiss German 


ESP 


Spanish 


PTB 


Brazilian Portuguese 


KOR 


Korean 


JPN 


Japanese 


CHS 


Simplified Chinese 


CHT 


Traditional Chinese 


FRA 


French 


ITA 


Italian 



If /NLS=xxx is not specified, the environment variable EZERNLS is checked. 
Either /NLS=xxx or EZERNLS must be specified. 
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Part 5. Running VisualAge Generator C++ programs 
CICS for Windows NT 
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Chapter 19. Preparing to Run C++ Programs on CICS for 
Windows NT 



VisualAge Generator Server for Windows NT enables you to install and run 
VisualAge Generator C++ programs in the CICS for Windows NT 
environment. 

This section contains information needed to prepare a generated C++ program 
to run in a Windows NT environment. During generation, several output files 
are created. These files are used when preparing your programs. 

The preparation step can be invoked by the program generator by specifying 
the Start preparation command file option in the options notebook, or by 
specifying the /PREP option when generating from the command line. The 
VisualAge Generator program generator cannot automatically start the 
preparation process for Windows NT. If the /PPvEP generation option is 
specified (if generating on a remote Windows NT machine), VisualAge 
Generator transfers all of the generated output to the Windows NT target 
system. You must manually start the preparation process by running the 
appnameZ.BAT file. The generation output files are described below. 



Generation Output Files 

The output files created at generation are placed in the generation output 
directory or the current directory if the / GENOUT option is not specified. See 
the VisualAge Generator Generation Guide for a list of these files and how to 
generate them. 



Preparing Your CICS for Windows NT C++ Program 

You must prepare your C++ programs before they can be run. This 
preparation step involves compiling the program and map source files into 
executable files. The file name extensions assigned to these executable output 
files differ depending on the type of source file and the compiler you use. See 
Table 11 for the extensions used on the executable files. 



Table 11. File Extensions for Executable Output Files 



Type of Source File 


Compiler Used 


Executable Output File 






Extension 


Main program 


VisualAge for C++ Compiler for 


.ibmcpp 




Windows NT 
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Table 11. File Extensions for Executable Output Files (continued) 



Type of Source File 


Compiler Used 


Executable Output File 
Extension 


Called program 


VisualAge for C++ Compiler lor 
Windows NT 


.ibmcpp 


Map group 


VisualAge for C++ Compiler for 
Windows NT 


.dll 


Main program 


Microsoft Visual C++ Compiler 


.cpp 


Called program 


Microsoft Visual C++ Compiler 


.cpp 


Map group 


Microsoft Visual C++ Compiler 


.dll 



Your C++ programs are compiled using either the VisualAge for C++ 
Compiler for Windows NT or Microsoft Visual C++ Compiler. We also use the 
nmake utility that comes with both compilers, nmake accepts as input a 
makefile which lists the source code and instructions for compiling and 
linking this source code. VisualAge Generator Server for Windows NT 
provides a makefile called FCWMAKE that contains instructions on how to 
compile the generated programs. 

There are two methods you can use to prepare your C++ generated programs: 

• Use the GENERATE subcommand and have the generator do the prepare. 
This subcommand transfers all parts of the program (programs, map 
groups, and tables) to the target system. 

• Use the PREPARE subcommand. If generation and preparation are being 
done on the same system, the parts are compiled and linked. 

Preparing Programs Using the Generate Subcommand of the HPTCMD 
Command 

The preparation process is automatically started by generation unless you 
specify the /NOPREP option on the GENERATE command or did not specify 
Start preparation command file in the options notebook. 

Automatic Preparation 

Additionally, the following options must be specified for preparation to be 
started: 

• /DBUSER=<NTdatabaseUserid> 

• /DBPASSWORD=<NTdatabasePassword> 

• /DESTHOST=<NThostName> 

• /DESTUID=<NTuserId> 

• /DESTPASSWORD=<NTUserPassword> 

• / DESTDIR=' <NTDirectory> ' 
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Note: The directory must be contained within single quotes and should be the 
full path name. The user must have write authority to the destination 
directory and files. 

If you choose this method to do your preparation, be sure that the 
FCWMAKE environment variable contains the name of the directory where 
the VisualAge Generator Server for Windows NT product was installed. This 
environment is set in the Windows NT Registry if you updated it during 
installation, or set by using the Control Panel. 

Preparing Programs Using the PREPARE Subcommand of the HPTCMD 
Command 

You may choose to run the preparation process independently from the 
generation process. To do this, specify the PREPARE subcommand . 

The PREPARE subcommand can only be issued through the VisualAge 
Generator command line interface. The interactive interface does not support 
the PREPARE subcommand. 

Manual Preparation 

The following options must be specified for preparation to be started on a 
remote CICS for Windows NT system: 

• /DBUSER=<NTdatabaseUserid> 

• / DBPASSWORD=<NTdatabasePassword> 

• / DESTHOST=<NThostName> 

• /DESTUID=<NTuserId> 

• /DESTPASSWORD=<NTUserPassword> 

• /DESTDIR='<NTDirectory>' 

The preparation process on CICS for Windows NT involves transferring the 
source objects (generated source, generated tables, and generated program 
specific utilities) to the target machine (if different from the generation 
machine). The program and all of its dependents are compiled and linked. 
The CICS resource definitions must then be added by running the 
prognameC.bat file. The program can then be run by entering the transaction id 
from a CICS window. 

Note: The prognameC.bat file is only created if the CICSENTRIES=RDO 
generation option is specified. 



Understanding Compiled Output Files 

The outputs you receive from program preparation are dynamic link libraries 
(DLLs) which, along with the .TAB files for tables, constitute the executable 
code for the program. The following DLLs are created for each program: 
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progname.ibmcpp or progname.cpp 

progname is the name of the program. If you are using VisualAge for 
C++, the extension will be .ibmcpp. If you are using Microsoft Visual 
C++, the extension is xpp. If the Microsoft Visual C++ compiler is 
used, the progname.cpp file that was output from the generation is 
renamed to progname.C and the resulting executable is progname.cpp. 
The FCWMAKE makefile performs the above processing. 

map.DLL 

map is the name of the main map group 
hlp.DLL 

hip is the name of the help map group 

The map.DLL and hlp.DLL are created only if a map group or help map 
group are defined for the program. 

In addition to the DLL output files, you will receive other files with 
extensions such as OBJ, DEF, MAP, SQC, BND. The .BND file should be saved 
in case the program is moved to another system so that the DB2 program 
package can be bound into the database on that system. All the other files are 
temporary files and can be deleted. 



Storing the Program Library 

The compiled program library you received at compilation time need to be 
placed in a directory specified in the PATH environment variable in your 
Windows NT environment. You can also set this up through your Control 
Panel in Windows NT. The .TAB files need to be placed in a directory 
specified in the FCWDPATH or the PATH environment variable. 
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Chapter 20. Customizing Your Workstation to Run C++ 
Programs on CICS for Windows NT 



This chapter describes the tasks that need to be performed to set up the 
workstation to run CICS for Windows NT programs. These tasks include the 
following program preparation steps: 

• Setting up environment variables 

• Creating a resource association file 



Environment Variable Settings 

Before you can run your programs, you need to perform the following tasks 
to set up the environment variables for the system: 

• Define product-specific environment variables 

• Modify the standard Windows NT-defined variables 

If you want to distribute C++ generated programs to other Windows NT 
systems, you need to set the environment variables on those systems too. 

Defining Product-Specific Environment Variables 

VisualAge Generator Server for Windows NT provides the following 
environment variables that must be added to the CICS for Windows NT 
environment file (\var\cics_regions\$CICSREGION\environment). 

Table 12. Product Specific Environment Variables for VisualAge Generator Server for 
Windows NT and Common Services 



Environment variable 


Runtime services 


Common services 


CSOTROPT 




Optional 


CSOTROUT 




Optional 


EZERJULS_xxx 


Optional 




EZERJULL_xxx 


Optional 




EZERGRGS_xxx 


Optional 




EZERGRGL_xxx 


Optional 




EZERNLS 


Required 


Optional 


EZERSQLDB 


Optional 




FCWCOMP 


Required 




FCWDBNOOP 


Optional 




FCWDBPASSWORD 


Optional 
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Table 12. Product Specific Environment Variables for VisualAge Generator Server for 
Windows NT and Common Services (continued) 

Environment variable Runtime services Common services 



FCWDBUSER 


Optional 


FCWDBVERSION 


Optional 
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FCWDPATH 


Required 


FCWFIODB 


Optional 


FCWMAKE 


Required 


FCWOPT 


Optional 


FCWTRDB_<tranid> 


Optional 


FCWTROPT 


Optional 


FCWTROUT 


Optional 



A typical CICS environment file might contain the following: 

CS0TR0PT=2 

EZERNLS=ENU 

EZERSQLDB=sampl e 

FCWDBUSER=vguser 

FCWDBPASSWORD=vguser 

FCWDPATH=d : \ci csgenout 

FCWTR0PT=31 

PATH=d:\ci csgenout ;%PATH% 

In addition, the value of EZERSQLDATE is used during generation to set the 
DB2 date and time format specified in the SQL preparation commands in 
prognameZ.CMD, the preparation command file created at that time. 

For more information on environment variables see "Appendix. VisualAge 
Generator Environment Variables" on page 245 and the VisualAge Generator 
Installation Guide document. 

Modifying the Standard Windows NT-Defined Variables 

Your PATH statement should contain the directory where the program DLLs 
are stored. This directory is usually the generation output directory. 

Table 13 shows the standard environment variables used with generated CICS 
for Windows NT C++ programs that can be customized. 

Table 13. Standard Environment Variables for VisualAge Generator Server for 
Windows NT and Common Services 

Environment variable Runtime services Common services 

HELP 
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Table 13. Standard Environment Variables for VisualAge Generator Server for 
Windows NT and Common Services (continued) 

Environment variable Runtime services Common services 

PATH Required Required 



Defining Programs to CICS for Windows NT 

Before a program can run in the CICS for Windows NT environment, the 
program, transaction, and its data files must be defined to CICS for 
Windows NT. 

Refer to the CICS Administration Reference for more information on defining 
resources to CICS for Windows NT. 

The following resource definitions are required: 

• Transaction definitions (TDs) 

• Program definitions (PDs) 

• File definitions (FDs) 

• Transient data definitions (TDDs) 

Sample transaction and program definitions using the cicsadd command are 
created at generation, if the CICSENTRIES=RDO generation option is 
specified. The generated command file is prognameC.bat. This script file must 
be run manually once for each CICS region. Before it is run, the CICS 
environment variable CICSREGION must specify the correct region name. 

Transaction Definitions 

A transaction definition is required for the following: 

• Each main program 

• Asynchronous programs you started through CREATX or specifying the RT 
generation option 

• Programs transferred to with an XFER statement 

• Programs transferred to by non- VisualAge Generator programs 

Program Definitions 

Program definitions are required for each program. The program definition 
should include at least the following attributes: 

PathName 

The directory and file name for the program executable. The file 
extension of .ibmcpp or .cpp should not be included. 

Note: The map group does not require a program definition. 

File Definitions 

File definitions are required for access to VSAM data set types. 
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Transient Data Definition 

Transient data definitions are required for serial program files associated with 
CICS transient data queues in the resource association table. 
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Chapter 21. Considerations for C++ SQL Programs on 
CICS for Windows NT 



The following sections provide information for preparing and running 
programs that access relational databases: 

• Accessing DB2 Databases 

• Accessing Oracle Databases 

• Environment Variables 

• Binding an Access Plan Using DB2 

• Code Page Considerations 

• Static Versus Dynamic SQL Statements 

• CICS for Windows NT SYNCPOINT Coordination 

• CICS for Windows NT Considerations for a DB2 File System 

• Performance Considerations 

• Accessing Distributed Databases 

• Oracle for Windows NT Version Considerations 

• Migrating Applications from Oracle 7 to Oracle 8 



Accessing DB2 Databases 

VisualAge Generator DB2 support provides direct access to DB2 databases 
without using Datajoiner. By specifying the /DBMS=DB2 generation option, 
the VisualAge Generator program is generated specifically for DB2. Additional 
information on using DB2 is documented in the VisualAge Generator Design 
Guide. 



Accessing Oracle Databases 

VisualAge Generator Oracle support provides direct access to Oracle 
databases without using Datajoiner. By specifying the /DBMS=ORACLE 
generation option, the VisualAge Generator program is generated specifically 
for Oracle. Additional information on using Oracle is documented in the 

VisualAge Generator Design Guide. 

Environment Variables 

The following environment variables are referenced in preparing and running 

a program containing SQL statements: 

DB2INSTANCE 

Specifies the name of the DB2 instance. (Applies to DB2 only.) 
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EZERSQLDB 

Specifies the VisualAge Generator Server default database (DB2 or 
Oracle). 
FCWDBNAME_<tranid> 

Specifies the name of the database (DB2 or Oracle) to be used by a 
specific VisualAge Generator Server transaction program. <tranid> is 
the CICS transaction ID. 

Notes: 

1 . For DB2, the name specified is the database alias name. 

2. For Oracle, the name specified must be a service name entry in the 
tnsnames.ora file. 

FCWDBNOOP 

Specifies that CICS XA definitions are being used for database access. 
VisualAge Generator will not attempt to coordinate CICS and 
database resources but instead allows CICS to handle resource 
coordination. 

FCWTRDB_tranid 

The name of the relational database to be used for a specific 
transaction. <tranid> is the CICS transaction ID. 

FCWDBVERSION 

Specifies the name of the database software installed on the 
Windows NT system. The value of FCWDBVERSION is used when 
preparing SQL programs for execution under Windows NT. 

Notes: 

1 . For DB2, this value is not used. 

2. For Oracle, supported values are 7 and 8. 
FCWFIODB 

The name of the file system database, if CICS is set up to use a DB2 
file system. You should only specify this environment variable if the 
CICS file system and user DB2 tables are located on different 
databases. 

EZERSQLDATE 

The value of the EZERSQLDATE environment variable during 
generation determines the DB2 date format generated for the 
precompiler step in the appnameZ.bat file. The appnameZ.bat file is 
used to make the program on the Windows NT system. 

ORACLE_HOME 

Specifies the directory containing the Oracle software. 

For more information on setting environment variables, see "Appendix. 
VisualAge Generator Environment Variables" on page 245. 
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Binding An Access Plan Using DB2 

An access plan must be built for each DB2 database a program uses before an 
SQL program can rim successfully. The process is called binding the program. 

The access plan is bound during the preparation process to the database used 
during the precompile step. Use the BIND command to bind the program to 
other databases. To use BIND, have the bind file produced during 
preparation, progname. BND, available and issue the following command under 
DB2 command line processor: 
BIND progname. BND 

Where progname. BND specifies the name of the program you want to run. 

If you do not specify a file name, the messages are directed to the standard 
output. 

To bind an SQL program, you must have the following authority: 

• READ authority to each table the program uses 

• WRITE authority to each table the program updates 

See your database administrator to get the required authorization. 

Refer to the VisualAge Generator Generation Guide for more information on 
performing binding as part of the program generation and preparation 
process. Refer to the Database 2 for Windows NT Command Reference for more 
information on the BIND command. 



Code Page Compatibility 

All SQL programs that use a relational database must use the same code page. 
When you create an SQL database in DB2 for Windows NT, the code page of 
the process that creates the database is associated with the SQL database. 



Static Versus Dynamic SQL Statements 

When unqualified table names are used in the SQL statements of a VisualAge 
Generator program, the implicit table qualification might be different for static 
mode SQL statements than for dynamic mode SQL statements. 

In static mode, SQL statements are resolved when the program is bound. All 
unqualified SQL table names are qualified with the USERID that is logged on 
to the workstation when the bind takes place. 
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In dynamic mode, SQL statements are resolved while the program is running. 
All unqualified SQL table names are qualified with the USERID that is logged 
on to the workstation where the program is running. 

Dynamic mode is used in the following situations: 

• When the Execution Time Statement Build option is specified for SQL 
statements in a generated program 

• When the table name of an SQL row record is defined as a host variable 

For more information on static mode versus dynamic mode, refer to the 

VisualAge Generator Design Guide. 



CICS for Windows NT SYNCPOINT Coordination 

By default, CICS for Windows NT coordinates commit and rollback of 
resources between CICS and the database manager by sequentially issuing a 
DB2 commit /rollback, followed by a CICS syncpoint syncpoint/ rollback. If 
you are using XA support, it is necessary that your system is set up to send a 
message to VisualAge Generator indicating that CICS is coordinating commit 
and rollback between CICS and the database manager. To set up this message 
link, set the FCWDBNOOP environment variable. This will indicate to 
VisualAge Generator not to attempt a DB2 commit / rollback at the end of the 
unit of work. 



CICS for Windows NT Considerations for a DB2 File System 

If you have setup CICS to use a DB2 file system versus a SFS file system, then 
you need to take into consideration how this affects your VisualAge Generator 
program. By default, the connection pointing to your DB2 file system that was 
established by CICS will be the active connection. If all of your user tables are 
also on this database, you do not need to worry about switching connections 
to your user databases. This means that you do not need to set the 
FCWFIODB, EZERSQLDB, and FCWTRDB_<tranid> environment variables. 

If your user data is on a different database, the user needs to ensure that the 
database connection is active before using the database. It is recommended 
that you have VisualAge Generator handle switching of the connections from 
dormant to active. VisualAge Generator will handle the switching of 
connections, if the following environment variables are set: 

FCWFI0DB=DB2 filesystem name 
EZERSQLDB=user database name 
FCWTRDB_<tranid>=user database name 

When you start CICS, the DB2 file system database connection will be active 
and all other connections will be dormant. When VisualAge Generator 
attempts a database I/O, VisualAge Generator will set the user database 
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connection active, perform the database I/O, and set the DB2 file system 
connection active. VisualAge Generator first uses FCWTRDB_<tranid>, if it is 
available. If not available, VisualAge Generator then uses EZERSQLDB for the 
user database name. 

VisualAge Generator uses temporary storage queues when performing 
printing operations. If you submit multiple, large print jobs, this might cause 
the DB2 file system to lock. 



Performance Considerations 

Refer to the CICS for Windows NT and DB2 for Windows NT documentation 
for more information on temporary storage queues when using DB2 as a file 
system. 



Accessing Distributed Databases 

The Distributed Database Connection Services for Windows NT licensed 
program provides access to any database manager enabled as a Distributed 
Remote Database Architecture (DRDA) server, including all members of the 
DB2 product family 

The DB2 Client Program Enabler for Windows NT licensed program provides 
access to DB2 workstation databases, including DB2 and DB2 CAE for 
Windows NT in conjunction with IBM Datajoiner, provides access to non-IBM 
relational databases including Oracle and Sybase databases. 

DDCS for Windows NT and DB2 CAE for Windows NT provides the same 
interface for binding and running programs that DB2 does. Refer to these 
products' documentation for more information. 



Oracle for Windows NT Version Considerations 

VisualAge Generator Server for Windows NT ships support for both the 
Oracle7 and Oracle8 client products and can be configured to use either one. 
The Oracle8 client is used by default. The Oracle7 and Oracle8 clients cannot 
be used simultaneously. For example, you cannot use the Oracle7 client for 
one application and the Oracle8 client for another without reconfiguring 
VisualAge Generator Server for Windows NT in between. 

A VisualAge Generator Server tool called orasetup is provided that allows 
you to configure the version of the Oracle client that VisualAge Generator 
Server should use. The orasetup tool is located in the \samples directory of 
the VisualAge Generator Server for Windows NT product installation 
directory (for example, c:\vgservw\samples). 
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To invoke the orasetup tool, issue the orasetup command from a command 
window within the product installation directory. The syntax is as follows: 

orasetup [ -i 7 | 8 ] [ -o 7 | 8 ] [ -csodir <directory> ] [ -fcwdir directory ] [-h|H|?] 
where 

-i Specifies the version of Oracle to change to. The default is 7. 

-o Specifies the current version of the Oracle client in use by VisualAge 
Generator Server for Windows NT. 

If no value is specified for this option, the value of the 
FCWDBVERSION environment variable is used. 

Note: The value of FCWDBVERSION is maintained using the 

orasetup tool. You should never need to manually set the value 
of FCWDBVERSION. 

-csodir 

Specifies the product installation directory for VisualAge Generator 
Common Services. The default is c:\hptcsow. 

-fcwdir 

Specifies the VisualAge Generator Server product installation 
directory. The default is c:\vgservw. 

-h I H I ? 

Displays help information for the orasetup tool. 

A slash ( / ) can be used in place of the dash ( - ) when specifying orasetup 
options. 

Note: To issue the orasetup command from any command line, you must 
manually add the / samples subdirectory of the product installation 
directory to your Windows NT PATH environment variable (for 
example, c:\vgservw\samples). 

When the values specified for -o and -i are different, orasetup does the 
following: 

• Swaps the current version of fcworcl.dll and csoora.dll for the specified 
version. 

• Updates the value of FCWDBVERSION in the Windows NT Registry. 

If the value of FCWDBVERSION ever becomes inconsistent with the current 
state of VisualAge Generator Server, you can determine the correct value by 
checking the \DLL directory of the VisualAge Generator Server product 
installation directory for the version of the Oracle modules that are not 
currently being used. For example, if the files fcworcl7.dll and csoora7.dll 
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exist in this directory, Oracle7 is not currently being used by VisualAge 
Generator Server. Hence, the current version of the Oracle client being used is 
version 8, and you should set FCWDBVERSION to 8. 

Similarly, if the -o option is not specified and the environment variable 
FCWDBVERSION does not exist or contains an invalid value, the orasetup 
tool checks the files in the \DLL directory to determine the current version. 

Note: The orasetup tool cannot update the value of FCWDBVERSION in any 
open command window or in any running applications. For orasetup 
changes to take effect, you must open new command windows and 
restart any running applications. 

For more information about the orasetup tool, see the orasetup.readme file in 
the \ samples directory of the VisualAge Generator Server for Windows NT 
product installation directory or execute the command orasetup -h. 



Migrating Applications from Oracle 7 to Oracle 8 

If you have migrated from the Oracle7 for Windows NT client to the Oracle8 
for Windows NT client on your Windows NT system, three migration paths 
are available for upgrading your VisualAge Generator applications that use 
the Oracle7 client library to use of the Oracle8 client library. Choose one of the 
following paths, depending upon the Oracle8 client / server features you plan 
on using: 

1 . If you do not want to use any of the new Oracle8 features, do nothing at 
all. The Oracle7 client library is provided with the Oracle8 client for 
compatibility. You can use your existing VisualAge Generator Oracle7 
applications to access both Oracle7 and Oracle8 databases without any 
modifications. However, when accessing Oracle8 databases through an 
Oracle7 client, none of the Oracle8-specific features (such as parallel 
execution of the INSERT statment) can be used. In this case, you will 
conceptually still be making Oracle7 connections. 

2. If you want to use new Oracle8 features that do not require recoding of 
the application, relink your VisualAge Generator Oracle7 applications with 
the Oracle8 client library. This allows you to take advantage of Oracle8 
features such as Improved Data Warehouse Performance. 

A batch file is provided with VisualAge Generator to help automate the 
relink process. The file is called orarelink.bat and is located in the 
\ samples directory of your VisualAge Generator Server for Windows NT 
product installation directory. 

The orarelink command syntax is as follows: 
orarelink [/h|H|?] appnamel appname2 ... 

where 
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appnamel wppnamel ... 

Specify the names of applications (separated by a blank space) that 
you would like to relink. 

hi HI ? 

Displays help information for the orarelink command. 

Notes: 

a. You can only specify applications that are in the current directory from 
which you issue the orarelink command. 

b. To issue the orarelink command from any command line, you must 
manually add the / samples subdirectory of the product installation 
directory to your Windows NT PATH environment variable (for 
example, c:\vgservw\samples). 

c. The appname parameters are application names, not the names of the 
z.bat files. For example, to relink a VisualAge Generator application 
named TEST1, you would issue the command orarelink TEST1. 

3. If you want to use new Oracle8 features that require recoding of the 
application, you must recode your VisualAge Generator applications. 
Recoding allows you to take advantage of Oracle8 features such as the 
Object Relational Technology. You must also regenerate and prepare any 
VisualAge Generator applications that you recode. 

Notes: 

1 . Oracle8 databases can be accessed using VisualAge Generator Oracle7 
applications. If you continue to use the Oracle7 client, no changes are 
necessary. Similarly, Oracle7 databases can be accessed using VisualAge 
Generator Oracle8 applications as long as the clients do not use any of the 
Object Relational Technology features of Oracle8. 

2. If you have applications that you have precompiled with the Oracle8 
precompiler, you cannot relink those applications with the Oracle7 client 
SQL library. The precompiler output is not backward compatible. 
However, applications that have been precompiled with the Oracle7 
precompiler can be relinked with the Oracle8 client SQL library. 

For more information on migrating existing Oracle7 precompiler applications 
to Oracle8 precompiler applications, refer to the documentation that came 
with your copy of the Oracle8 for Windows NT client. For more information 
about the orarelink tool, see the orarelink.readme file in the \samples 
directory of the VisualAge Generator Server for Windows NT product 
installation directory or issue the command orarelink /h. 
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Chapter 22. Running VisualAge Generator C++ Programs 
on CICS for Windows NT 



To run a program under CICS for Windows NT, start a CICS for 
Windows NT terminal and enter the name of the transaction associated with 
the program. Refer to your CICS for Windows NT documentation for other 
methods for starting transactions. 

Note: The transaction ID must be specified in uppercase. 



National Language Versions Considerations 

VisualAge Generator Server for Windows NT provides support for more than 
one national language. You can install multiple language versions of 
VisualAge Generator Server for Windows NT on one workstation, although 
only one language can be loaded each time the product is started. VisualAge 
Generator Server for Windows NT supports double-byte character sets on 
those workstations that provide double-byte support. 

VisualAge Generator Server for Windows NT does not perform run time code 
page switching or data translation to make the process, keyboard, and display 
devices conform to the language being used. You must configure the 
appropriate code page for VisualAge Generator Server for Windows NT to 
run. Refer to the CICS for Windows NT documentation for more information 
on managing country code information and code page switching. Refer to the 
VisualAge Generator Client/Server Communications Guide and VisualAge 
Generator Installation Guide documents for more information on national 
language coge pages. 

For more information on SQL programs, see "Chapter 21. Considerations for 
C++ SQL Programs on CICS for Windows NT" on page 107. 
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Part 6. Running VisualAge Generator C++ programs on 
HP-UX 
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Chapter 23. Preparing to Run C++ Programs on HP-UX 



After a VisualAge Generator HP-UX program has been generated, the 
generated objects must be moved to an HP-UX system and prepared before 
you can run the program. For HP-UX, preparation includes compiling and 
linking generated C++ programs. The C++ Generator creates the control files 
to send the appropriate source to the remote machine and start the make 
process on that machine. 

Preparation can be started automatically following the generate process, or it 
can be started manually with the Prepare subcommand of HPTCMD. 



Automatic Preparation 

The preparation process is automatically started by generation unless you 
specify the /NOPREP option on the generate command or did not specify 
Start preparation command file in the options notebook. 

Additionally, the following options must be specified for preparation to be 
started: 

• /DBUSER=<HP-UXdatabaseUserid> 

• / DBPASSWORD=<HP-UXdatabasePassword> 

• /DESTHOST=<HP-UXhostName> 

• /DESTUID=<HP-UXuserId> 

• / DESTPASSWORD=<HP-UXUserPassword> 

• /DESTDIR='<HP-UXDirectory>' 

Note: The directory must be contained within single quotes and should be the 
full path name. The user must have the following: 

• rexec authority to the target HP-UX host machine 

• write authority to the destination directory and files 

Manual Preparation 

You can run the preparation process independently from the generation 
process using the PREPARE subcommand. 

The PREPARE subcommand can be issued only through the VisualAge 
Generator program generator command line interface. The interactive interface 
does not support the PREPARE subcommand. 

The following options are required: 

• /DBUSER=<HP-UXdatabaseUserid> 
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• /DBPASSWORD=<HP-UXdatabasePassword> 

• /DESTHOST=<HP-UXhostName> 

• /DESTUID=<HP-UXuserId> 

• /DESTPASSWORD=<HP-UXUserPassword> 

• /DESTDIR='<HP-UXDirectory>' 

The preparation process in the HP-UX environment involves transferring the 
source objects (generated source, generated tables, and generated program 
specific utilities) to the target HP-UX host machine, and remotely invoking the 
compiler and linker on that machine. 

The program can then be run at the target HP-UX machine, by using the 
following command: 
fcwrun progname 



Generation Output Files 

The output files created at generation are placed in the generation output 
directory or the current directory if the / GENOUT option is not specified. See 
the VisualAge Generator Generation Guide for a list of these files and how to 
generate them. 



Understanding Compiled Output Files 

The output you receive from the compile of your program and map group is 
a shared library which contains the executable code for the program. This file 
has an extension of .si. 

The outputs you receive from program preparation are source libraries (SLs) 
which, along with the .TAB files for tables, constitute the executable code for 
the program. The following SLs are created for each program: 

progname.sl 

progname is the name of the program 

map. si map is the name of the main map group 
hip. si hip is the name of the help map group 

The map. si and hlp.sl are created only if a map group or help map group is 
defined for the program. 

In addition to the progname.sl output file, you receive other files with 
extensions such as .0 and .bnd. The .0 (object) files can be deleted; save the 
.bnd files for binding SQL programs to other databases, if the program must 
be moved to other systems. All the other files are temporary files and can be 
deleted. 
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Placing Shared Libraries 

The shared libraries created during preparation will be in the directory 
specified in the /DESTDIR generation option. This directory must be in the 
path defined in the SHLIB_PATH environment variable or in the current 
directory of the process executing the fcwrun command. 
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Chapter 24. Customizing Your Workstation to Run C++ 
Programs on HP-UX 

This chapter describes the tasks that need to be performed to set up the 
workstation to run HP-UX programs. These tasks include the following 
program preparation steps: 

• Setting environment variables 

• Creating a resource association file 

Before you can run your programs, you need to set the required environment 
variables for the system. 

If you want to distribute C++ generated programs to other HP-UX systems, 
you need to set the environment variables on those systems too. 



Defining the Environment Variables 

VisualAge Generator Server provides the following environment variables that 
you can add to your .profile or you can set them from the HP-UX command 
line when setting up your environment to run programs. 

You must consider all the HP-UX environment variables when configuring 
your workstation to run HP-UX programs. Table 14 shows the product-specific 
environment variables that can be customized for HP-UX. 

Table 14. Product Specific Environment Variables for HP-UX 
Environment variable HP-UX runtime 



CSOTROPT 


Optional 


CSOTROUT 


Optional 


DB2INSTANCE 


Required 


EZEGRGL_xxx 


Optional 


EZEGRGS_xxx 


Optional 


EZEJULL_xxx 


Optional 


EZEJULS_xxx 


Optional 


EZERNLS 


Required 


EZERSQLDB 


Optional 


FCWDB2DIR 


Required (if accessing DB2 HP-UX) 


FCWDBNAME_<progname> 


Optional 
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Table 14. Product Specific Environment Variables for HP-UX (continued) 
Environment variable HP-UX runtime 



FCWDBPASSWORD 


Optional 


FCWDBUSER 


Optional 


FCWDPATH 


Optional 


FCWLIBPATH 


Optional 


FCWRSC 


Optional 


FCWOPT 


Optional 


FCWTROPT 


Optional 


FCWTROUT 


Optional 


ORACLE_HOME 


Optional 


PATH 


Required 



SHLIB_PATH Required 



A typical profile might contain the following VAGen environment settings: 
CS0TR0PT=2 

CSOTROUT=csotrace.out 

DB2INSTANCE=db2inst2 

DPATH=/opt/vgwgs45 : /opt/vgwgs45/l i b 

EZERNLS=ENU 

EZERSQLDB=sampl e 

FCWDB2DIR=/opt/IBMdb2/V2.1 

FCWDBPASSWORD=vguser 

FCWDBUSER=vguser 

FCWDPATH=/home/vguser/genout 

FCWLIBPATH=/home/vguser/genout 

FCWTR0PT=31 

FCWTROUT=fcwtrace.out 

LANG=en_US.iso88591 

PATH=/opt/vgwgs45/bi n : $PATH 

SHLIB_PATH=/lib:/usr/lib:/opt/vgwgs45/lib:$SHLIB_PATH 

In addition, the value of EZERSQLDATE (on the generation machine) is used 
during generation to set the DB2 date and time format. 

Refer to "Appendix. VisualAge Generator Environment Variables" on page 245 
for further descriptions of these environment variables. 
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Resource Association File 

If the program you are running accesses files, a resource association file must 
be created, with an entry for each serial or message queue record defined in 
the program. The resource association file is also used when your program 
contains printer maps and you want the output directed to a printer queue 
instead of the default output file (appName.map). In the HP-UX environment, 
the resource association file is used at run time, not at generation time. 

Creating Resource Association Files 

You can create and edit resource association files using a standard editor. You 
can enter options and values in uppercase or lowercase. All of the options can 
span lines. 

Comments are permitted and can appear anywhere in the file. Comments 
begin with the characters /* and end with the characters */. 

The default resource association file name is FCW.RSC. You can override the 
default file name by specifying the /R parameter at run time or by specifying 
a filename in the FCWRSC environment variable. For more information on 
using the /R option, see "Chapter 30. Distributing and Running C++ 
Programs on AIX" on page 161. 

The following diagram shows the syntax of the entries in the resource 
association file. 

►» — ASSOCIATE — FILE=/i lename- 



LETYPE= 



-MQ 

-SEQ — 
-SP00L- 



L/contableJ L/nofF- 



-/NOREPLACE- 



-/REPLACE- 



L/SYSNAME=system resource name-^ \—/SYSTEV\=target system- 



L/textJ 



ASSOCIATE 

Associates the file name specified in a record definition or the printer 
file with the physical file that is used for the record at run time 

FILE Specifies the file name in the record for which you are defining 
system resource association information 
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The file name can be EZEPRINT (the print file for the program) or 
one of the file names specified for a serial, indexed, or relative record 
used by the program. 

/FILETYPE 

Specifies the implementation of the file in a target environment 

The valid file types are system-dependent. Table 17 on page 150 shows 
the valid file types for each environment. 

The file type can be one of the following: 

MQ Specifies a message queue file. 

SEQ Specifies a serial or print file associated with a system 
sequential file for the HP-UX environment. 

SPOOL 

Specifies a printer file. The /SYSNAME parameter specifies 
the name of the output queue. 

/CONTABLE 

Specifies a conversion table name if you want data format conversion 
to be performed on a message. The / CONTABLE entry applies only 
to files where /FILETYPE=MQ. 

If you want data format conversion to be performed on the message, 
specify a conversion table name as shown in the following example: 
/CONTABLE=conversion_tabl e_name 

If a conversion table is specified, VisualAge Generator converts the 
message from local format to remote format when the message is 
added to the queue, and from remote format to local format when the 
message is read from the queue. VisualAge Generator performs 
conversion using the message queue record structure to identify the 
data type of fields in the message. 

Specify EZECONVT for the conversion table name if you want the 
conversion table name to be picked up at run time from the 
EZECONVT special function word. 

/NOFF 

Specifies that a form feed should not be issued during Close 
processing for a map. 

/REPLACE or /NOREPLACE 

Specifies whether an existing serial file is replaced by the new one 
that is written by the program. 

You can specify /REPLACE with file type SEQ for the HP-UX 
environment. If /REPLACE is specified, the first ADD to a serial file 
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in a program, or the first ADD to a serial file following a CLOSE, 
adds the record to the beginning of the file. Previous file contents are 
lost. 

The /REPLACE or /NOREPLACE option is only valid for serial 
(SEQ) files. 

You can use /NOREPLACE to specify that an ADD to a file always 
appends to the end of the file. If /NOREPLACE is specified, ADD 
always adds a record to the end of the current file. /NOREPLACE is 
the default. 

/SYSNAME 

Specifies the system name of the file associated with the file name in 
the record. If /FILETYPE=SPOOL, /SYSNAME specifies an output 
queue name. If /FILETYPE=MQ, /SYSNAME specifies the queue 
manager name and queue name. 

The format of the name is system-dependent. If /FILETYPE=MQ, use 
the syntax shown in the following example: 
/SYSN/\ME=queue_manager_name:queue_naine 

/SYSTEM 

Specifies the target system affected by this associate command 

You might have multiple associates in one resource association file. 
The resource association used is the first association where the value 
specified for the /SYSTEM option matches the value specified for the 
/SYSTEM generation option value. 

The target system value is HPUX. 

/TEXT Specifies a special type of serial file that contains line feed (LF) 

characters at the end of each line. When a record is read (SCAN), the 
LF characters are automatically removed. When a record is written 
(ADD), the LF characters are automatically appended to the end of 
each record. This option is useful when exchanging data files with 
other software packages that expect each record to be delimited with 
the LF characters. 

Example of Resource Association File Entries 

Figure 7 shows examples of resource association file entries. 

ASSOCIATE FI LE= FI LEI /SYSTEM=HPUX /FILETYPE=SEQ 

/SYSNAME=MYFILE.DAT 
ASSOCIATE FI LE=EZEPRINT /SYSTEM=HPUX /FI LETYPE=SP00L /SYSNAME=PRTQ1 
ASSOCIATE FILE=EZEPRINT /FI LETYPE=SEQ /SYSNAME=PRTMAP . OUT 



Figure 7. Examples of Resource Association File Entries 
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File Types Supported by Environment and Record Organization 

Table 15 shows the valid file types for the HP-UX environment. 

Table 15. File Types Supported by Environment and Record Organization 

Message 

System Indexed Queue Relative Serial Print 

HP-UX N/A MQ N/A SEQ SEQ 

SPOOL 
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Chapter 25. Considerations for C++ SQL Programs on 
HP-UX 



The following sections provide information for preparing and running 
programs that access relational databases: 

• Accessing DB2 Databases 

• Accessing Oracle Databases 

• Accessing Databases Using ODBC 

• Environment Variables 

• Binding an Access Plan Using DB2 

• Code Page Considerations 

• Static Versus Dynamic SQL Statements 

• Accessing Distributed Databases 

• DB2 for HP-UX Version Incompatibilities 

• Oracle for HP-UX Version Considerations and Incompatibilities 

• Migrating Applications from Oracle 7 to Oracle 8 



Accessing DB2 Databases 

VisualAge Generator DB2 support provides direct access to DB2 databases 
without using Datajoiner or ODBC. By specifying the /DBMS=DB2 generation 
option, the VisualAge Generator program is generated specifically for DB2. 
Additional information on using DB2 is documented in the VisualAge 
Generator Design Guide. 



Accessing Oracle Databases 

VisualAge Generator Oracle support provides direct access to Oracle 
databases without using Datajoiner or ODBC. By specifying the 
/DBMS=ORACLE generation option, the VisualAge Generator program is 
generated specifically for Oracle. Additional information on using Oracle is 
documented in the VisualAge Generator Design Guide. 



Accessing Databases Using ODBC 

VisualAge Generator ODBC support provides access to a variety of relational 
databases. By specifying the /DBMS=ODBC generation option, the VisualAge 
Generator program is generated specifically for ODBC. A VisualAge Generator 
ODBC program contains dynamic SQL statements as opposed to the static 
SQL statements that are generated for DB2 and Oracle. Additional information 
on using ODBC is documented in the VisualAge Generator Design Guide. 
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Environment Variables 

The following environment variables are referenced in preparing and running 

a program containing SQL statements: 

DB2INSTANCE 

Specifies the name of the DB2 instance. (Applies to DB2 only.) 
EZERSQLDB 

Specifies the VisualAge Generator Server default database (DB2, 
Oracle, or ODBC). 
FCWDBNAME_<progname> 

Specifies the name of the database to be used by a specific VisualAge 
Generator program (DB2, Oracle, or ODBC). 

Notes: 

1 . For DB2, the name specified is the database alias name. 

2. For Oracle, the name specified must be a service name entry in the 
tnsnames.ora file. 

3. For ODBC, the name specified must be an entry in the odbc.ini 
file. 

EZERSQLDATE 

The value of the EZERSQLDATE environment variable during 
generation determines the DB2 date format generated for the 
precompiler step in the appnameZ.scr file. The appnameZ.scr file is 
used to make the program on the HP-UX system. 
ORACLE_HOME 

Specifies the directory containing the Oracle for HP-UX software. 

For more information on setting environment variables, see "Appendix. 
VisualAge Generator Environment Variables" on page 245. 

Binding An Access Plan Using DB2 

An access plan must be built for each DB2 database a program uses before an 
SQL program can run successfully. The process is called binding the program. 

The access plan is bound during the preparation process to the database used 
during the precompile step. Use the BIND command to bind the program to 
other databases. To use BIND, have the bind file produced during 
preparation, progname.BNT), available and issue the following command under 
the DB2 command line processor: 
BIND progname. BND 

Where progname.BNT) specifies the name of the program you want to run. 

To bind an SQL program, you must have the following authority: 
• READ authority to each table the program uses 



130 VisualAge Generator: VisualAge Generator Server Guide for Workstation Platforms 



• WRITE authority to each table the program updates 

See your database administrator to get the required authorization. 

Refer to the VisualAge Generator Generation Guide for more information on 
performing binding as part of the program generation and preparation 
process. Refer to the IBM DB2 Command Reference for more information on the 
BIND command. 



Code Page Compatibility 

All SQL programs that use a relational database must use the same code page. 
When you create an SQL database in DB2 for AIX, the code page of the 
process that creates the database is associated with the SQL database. 



Static Versus Dynamic SQL Statements 

When unqualified table names are used in the SQL statements of a VisualAge 
Generator program, the implicit table qualification might be different for static 
mode SQL statements than for dynamic mode SQL statements. 

In static mode, SQL statements are resolved when the program is bound. All 
unqualified SQL table names are qualified with the USERID that is logged on 
to the workstation when the bind takes place. 

In dynamic mode, SQL statements are resolved while the program is running. 
All unqualified SQL table names are qualified with the USERID that is logged 
on to the workstation where the program is running. 

Dynamic mode is used in the following situations: 

• When the Execution Time Statement Build option is specified for SQL 
statements in a generated program 

• When the table name of an SQL row record is defined as a host variable 

For more information on static mode versus dynamic mode, refer to the 

VisualAge Generator Design Guide. 



Accessing Distributed Databases 

The Distributed Database Connection Services for HP-UX licensed program 
provides access to any database manager enabled as a Distributed Remote 
Database Architecture (DRDA) server, including all members of the DB2 
product family. 

The DB2 Client Program Enabler for HP-UX licensed program provides access 
to DB2 workstation databases, including DB2 and DB2 CAE for HP-UX in 
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conjunction with IBM Datajoiner, provides access to non-IBM relational 
databases including Oracle and Sybase databases. 

DDCS for HP-UX and DB2 CAE for HP-UX provides the same interface for 
binding and running programs that DB2 does. Refer to these products' 
documentation for more information. 



Oracle for HP-UX Version Considerations and Incompatibilities 

VisualAge Generator Server for HP-UX ships support for both the Oracle7 
and Oracle8 client products and can be configured to use either one. The 
Oracle8 client is used by default. The Oracle7 and Oracle8 clients cannot be 
used simultaneously. For example, you cannot use the Oracle7 client for one 
application and the Oracle8 client for another without reconfiguring 
VisualAge Generator Server for HP-UX in between. 

A VisualAge Generator Server tool called orasetup is provided that allows 
you to configure the version of the Oracle client that VisualAge Generator 
Server should use. The orasetup tool is located in the / samples directory of 
the VisualAge Generator Server for HP-UX product installation directory (for 
example, / opt/ vgwgs40/ samples). 

To invoke the orasetup tool, issue the orasetup command from a command 
window within the product installation directory. The syntax is as follows: 
orasetup [ -i 7 | S ] [ -o 7 | 8 ] [ -fcwdir directory ] [-h|H|?] 

where 

-i Specifies the version of Oracle to change to. The default is 7. 

-o Specifies the current version of the Oracle client in use by VisualAge 
Generator Server for HP-UX. 

If no value is specified for this option, orasetup checks the /lib 
directory of the VisualAge Generator Server for HP-UX product 
installation directory for the version of the Oracle modules that are 
not currently being used. For example, if the files fcworcl7.sl and 
csoora7.sl exist in this directory, Oracle7 is not currently being used 
by VisualAge Generator Server. Hence, the current version is 8. 

-fcwdir 

Specifies the VisualAge Generator Server product installation 
directory. The default is /opt/vgwgs40. 

-h I H I ? 

Displays help information for the orasetup tool. 
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When the values specified for -o and -i are different, orasetup swaps the 
current version of fcworcl.sl and csoora.sl for the specified version. 

Notes: 

1 . The FCWDBVERSION environment variable is not used on HP-UX. 

2. To issue the orasetup command from any command line, you must 
manually add the / samples subdirectory of the product installation 
directory to your HP-UX PATH statement (for example, 

/ opt/vgwgs40/ samples). 

For more information about the orasetup tool, see the orasetup.readme file in 
the /samples directory of the Visual Age Generator Server for HP-UX product 
installation directory or issue the command orasetup -h. 

The VisualAge Generator Server for HP-UX Oracle interface modules, 
fcworcl.sl and csoora.sl, are very sensitive to the version of Oracle for HP-UX 
on which they were built versus where they execute. The Oracle8 interface 
modules shipped with VisualAge Generator Server for HP-UX were built on 
an Oracle Version 8.0.3 system. The Oracle7 interface modules shipped with 
VisualAge Generator Server for HP-UX were built on an Oracle Version 7.3.4 
system. If a VisualAge Generator SQL program is rim on an HP-UX system 
with a version of Oracle for HP-UX at a higher release or maintenance level 
than either 7.3.4 or 8.0.3, it could receive the following message: 
FCWG012E Load Module fcworcl.sl cannot be loaded. The return code is 2. 

If you are running a version of Oracle for HP-UX at a higher release or 
maintenance level than either 7.3.4 or 8.0.3 and receive message FCW0012E, 
use these steps to correct the error: 

1 . Login as root. 

2. Ensure the ORACLE_HOME environment variable is set to point to the 
product installation directory of the version of the Oracle for HP-UX client 
you want to use. 

3. Change to the /samples directory of the VisualAge Generator Server for 
HP-UX product installation directory (for example, 

/ opt/vgwgs40/ samples). 

4. Build the VisualAge Generator Server for HP-UX Oracle7 modules using 
this command: 

make -f 1 inkorcl .mak FCWDBVERSI0N=7 

Build the VisualAge Generator Server for HP-UX Oracle8 modules using 
this command: 
make -f 1 inkorcl .mak 

Step 4 above builds new versions of either the VisualAge Generator Server for 
HP-UX Oracle7 or Oracle8 modules customized for your environment and 
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copies the new fcworcl.sl and csoora.sl files to your VisualAge Generator 
Server for HP-UX /lib directory. The existing copies are backed up in the 
same directory and renamed with a .save extension. If you do not wish to 
have the makefile automatically install these files, follow steps 1 through 3 
above and then do the following: 

1 . To build the VisualAge Generator Server for HP-UX Oracle7 modules, type 
the following command at the command prompt: 

make -f linkorcl .mak FCWDBVERSI0N=7 build 

To build the VisualAge Generator Server for HP-UX Oracle8 modules, type 
the following command at the command prompt: 
make -f linkorcl .mak build 

2. To install the resulting modules by hand, type the following two 
commands at the command prompt, replacing vgwgs with the path to your 
VisualAge Generator Server for HP-UX product installation directory (for 
example, /usr/lpp/vgwgs40): 

cp fcworcl.sl ygwgs/1 i b/fcworcl .si 
cp csoora.sl vgwgs/lib/csoora.sl 

3. To install the resulting modules using the makefile, type the following 
command at the command prompt: 

make -f linkorcl .mak install 

Note: You do not need to specify FCWDBVERSION with the make 
command in this step. 

For more information about building VisualAge Generator Server for HP-UX 
Oracle7 and Oracle8 modules, see the linkorcl.readme file in the / samples 
directory of the VisualAge Generator Server for HP-UX product installation 
directory. 



Migrating Applications from Oracle 7 to Oracle 8 

If you have migrated from the Oracle7 for HP-UX client to the Oracle8 for 
HP-UX client on your HP-UX system, two migration paths are available for 
upgrading your VisualAge Generator applications that use the Oracle7 client 
library to use of the Oracle8 client library. Choose one of the following paths, 
depending upon the Oracle8 client /server features you plan on using: 

1 . If you do not want to use any of the new Oracle8 features or you want to 
use new Oracle8 features that do not require recoding of the application, 
relink your VisualAge Generator Oracle7 applications with the Oracle8 
client library. This allows you to take advantage of Oracle8 features such 
as Improved Data Warehouse Performance. 
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A k-shell script is provided with VisualAge Generator Server to help 
automate the relink process. The script is called orarelink and is located in 
the /samples directory of your VisualAge Generator Server for HP-UX 
product installation directory. 

The orarelink command syntax is as follows: 

orarelink [-a] [-f filename] [appnamel appname2 ...] [-h[H|?] 

where 

-a Specifies that you would like to relink all applications in the 
current directory (determined by searching for all files named 
*z.scr). 

-f Specifies the name of a file that contains the names of programs to 
relink in the current directory. The file should contain only one 
program name per line. Optional comment lines can be included 
by placing a pound sign (#) at the beginning of the comment line. 

appnamel appnamel ... 

Specify the names of applications (separated by a blank space) that 
you would like to relink. 

hlHI? 

Displays help information for the orarelink command. 

Notes: 

a. You can only specify applications that are in the current directory from 
which you issue the orarelink command. 

b. To issue the orarelink command from any command line, you must 
manually add the / samples subdirectory of the product installation 
directory to your HP-UX PATH statement (for example, 

/ opt/vgwgs40/ samples). 

c. The appname parameters are application names, not the names of the 
appnamez.scr files. For example, to relink a VisualAge Generator 
application named TEST1, you would issue the command orarelink 
TEST1. 

d. Even if you do not want to use any of the Oracle8 features, relinking 
is required if you want to use the Oracle8 for HP-UX client software 
with your VisualAge Generator applications. 

2. If you want to use new Oracle8 features that require recoding of the 
application, you must recode your VisualAge Generator applications. 
Recoding allows you to take advantage of Oracle8 features such as the 
Object Relational Technology. You must also regenerate and prepare any 
VisualAge Generator applications that you recode. 
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Notes: 

1 . Oracle8 databases can be accessed using VisualAge Generator Oracle7 
applications. If you continue to use the Oracle7 client, no changes are 
necessary. Similarly Oracle7 databases can be accessed using VisualAge 
Generator Oracle8 applications as long as the clients do not use any of the 
Object Relational Technology features of Oracle8. 

2. If you have applications that you have precompiled with the Oracle8 
precompiler, you cannot relink those applications with the Oracle7 client 
SQL library. The precompiler output is not backward compatible. 
However, applications that have been precompiled with the Oracle7 
precompiler can be relinked with the Oracle8 client SQL library. 

For more information on migrating existing Oracle7 precompiler applications 
to Oracle8 precompiler applications, refer to the documentation that came 
with your copy of the Oracle8 for HP-UX client. For more information about 
the orarelink tool, see the orarelink.readme file in the / samples directory of 
the VisualAge Generator Server for HP-UX product installation directory or 
issue the command orarelink -h. 
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Chapter 26. Distributing and Running C++ Programs on 
HP-UX 



After the compiled program shared library files are placed in a directory on 
your system, the program is ready to be distributed and run on any 
supported system that has Visual Age Generator Server for HP-UX installed. 
To run your programs, VisualAge Generator provides the FCWRUN command 
with the /r and /nls options. HP-UX is case sensitive so you must type 
commands and parameters in the exact case specified. The FCWRUN 
command, / r and / nls options are described below. 



FCWRUN Command 

To run a generated and compiled VisualAge Generator main program, enter 
the following command: 
fcwrun progname 

Where progname is the name of the program. Do not include the .si extension. 

Note: If the EZERNLS environment variable has not been set, you must 
specify the / nls parameter. 

You can only run main programs using the fcwrun command. Called 
programs can be run by a call from another VisualAge Generator program or 
a 3GL program. 



Using the /r Option 

You can use the / r optional parameter with the FCWRUN command to 
specify the name of a resource association file. If you do not specify this 
option, the default filename fcw.rsc is used. For example, if the resource 
association filename is progl.rsc, and the program name is progl, use the 
following command: 

fcwrun progl /r=progl.rsc 

The resource association file can be qualified with a path name. If it is not 
fully qualified, it will be searched for in the following locations: 

• The current directory 

• The directories specified by the FCWDPATH environment variable 

You can also specify the resource association file using the FCWRSC 
environment variable. 
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Using the /nls Option 

VisualAge Generator provides a /nls option to specify the language version of 
VisualAge Generator Server you want to use and the program message tables 
to use. To use this option, enter the following command: 
fcwrun mainapp /nls=xxx 

Where a valid NLS code. 

The following are the valid NLS codes for VisualAge Generator Server: 



Valid Code 


Language 


ENU 


English 


DEU 


German 


DES 


Swiss German 


ESP 


Spanish 


PTB 


Brazilian Portuguese 


KOR 


Korean 


JPN 


Japanese 


CHS 


Simplified Chinese 


CHT 


Traditional Chinese 


FRA 


French 


ITA 


Italian 



If / nls=xxx is not specified, the environment variable EZERNLS is checked. 
Either / nls=xxx or EZERNLS must be specified. 
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Part 7. Running VisualAge Generator C++ programs on 
AIX 
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Chapter 27. Preparing to Run C++ Programs on AIX 



After a VisualAge Generator AIX program has been generated, the generated 
objects must be moved to an AIX system and prepared before you can run the 
program. For AIX, preparation includes compiling and linking generated C++ 
programs. The C++ Generator creates the control files to send the appropriate 
source to the remote machine and start the make process on that machine. 

Preparation can be started automatically following the generate process, or it 
can be started manually with the Prepare subcommand of HPTCMD. 



Automatic Preparation 

The preparation process is automatically started by generation unless you 
specify the /NOPREP option on the generate command or did not specify 
Start preparation command file in the options notebook. 

Additionally, the following options must be specified for preparation to be 
started: 

• /DBUSER=<AIXdatabaseUserid> 

• / DBPASSWORD=< AIXdatabasePassword> 

• / DESTHOST=< AIXhostName> 

• /DESTUID=<AIXuserId> 

• / DESTPASSWORD=< AIXUserPassword> 

• /DESTDIR='<AIXDirectory>' 

Note: The directory must be contained within single quotes and should be the 
full path name. The user must have the following: 

• rexec authority to the target AIX host machine 

• write authority to the destination directory and files 

Manual Preparation 

You can run the preparation process independently from the generation 
process using the PREPARE subcommand. 

The PREPARE subcommand can be issued only through the VisualAge 
Generator program generator command line interface. The interactive interface 
does not support the PREPARE subcommand. 

The following options are required: 

• /DBUSER=<AIXdatabaseUserid> 

• / DBPASSWORD=< AIXdatabasePassword> 
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• /DESTHOST=<AIXhostName> 

• /DESTUID=<AIXuserId> 

• /DESTPASSWORD=<AIXUserPassword> 

• /DESTDIR='<AIXDirectory>' 

The preparation process in the AIX environment involves transferring the 
source objects (generated source, generated tables, and generated program 
specific utilities) to the target AIX host machine, and remotely invoking the 
compiler and linker on that machine. 

The program can then be run at the target AIX machine, by using the 
following command: 
fcwrun progName 



Generation Output Files 

Place the output files created at generation in the generation output directory. 
See the VisualAge Generator Generation Guide for a list of these files and how to 
generate them. 



Understanding Compiled Output Files 

The outputs you receive from program preparation are dynamic link libraries 
(DLLs) which, along with the .TAB files for tables, constitute the executable 
code for the program. The following DLLs are created for each program: 

progname.DLL 

progname is the name of the program 

map.DLL 

map is the name of the main map group 
hlp.DLL 

hip is the name of the help map group 

The map.DLL and hlp.DLL are created only if a map group or help map 
group is defined for the program. 

In addition to the DLL output files, you will receive other files with 
extensions such as .0 and .bnd. The .0 (object) files can be deleted; save the 
.bnd files for binding SQL programs to other databases, if the program is 
moved to another system. All the other files are temporary files and can be 
deleted. 
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Placing Shared Libraries 

The shared libraries created during preparation will be in the directory 
specified in the /DESTDIR option. This directory must be in the path defined 
in the FCWLIBPATH environment variable or in the current directory of the 
process executing the fcwrun command. 
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Chapter 28. Customizing Your Workstation to Run C++ 
Programs on AIX 

This chapter describes the tasks that need to be performed to set up the 
workstation to run AIX programs. These tasks include the following program 
preparation steps: 

• Setting environment variables 

• Creating a resource association file 

Before you can run your programs, you need to set the required environment 
variables for the system. 

If you want to distribute C++ generated programs to other AIX systems, you 
need to set the environment variables on those systems too. 



Defining the Environment Variables 

VisualAge Generator Server for AIX provides the following environment 
variables that you can add to your .profile or you can set them from the AIX 
command line when setting up your environment to run programs. 

You must consider all the AIX environment variables when configuring your 
workstation to run AIX programs. Table 16 shows the product-specific 
environment variables that can be customized for AIX. 



Table 16. Product Specific Environment Variables for AIX 
Environment variable AIX runtime 



CSOTROPT 


Optional 


CSOTROUT 


Optional 


DB2INSTANCE 


Required 


EZEGRGL_xxx 


Optional 


EZEGRGS_xxx 


Optional 


EZEJULL_xxx 


Optional 


EZEJULS_xxx 


Optional 


EZERNLS 


Required 


EZERSQLDB 


Optional 


FCWDB2DIR 


Required (if accessing DB2 for AIX) 


FCWDBNAME_<progname> 


Optional 
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Table 16. Product Specific Environment Variables for AIX (continued) 
Environment variable AIX runtime 



FCWDBPASSWORD 


Optional 


FCWDBUSER 


Optional 


FCWDPATH 


Optional 


FCWLIBPATH 


Optional 


FCWRSC 


Optional 


FCWOPT 


Optional 


FCWTROPT 


Optional 


FCWTROUT 


Optional 


LIBPATH 


Required 


ORACLE_HOME 


Optional 


PATH 


Required 



A typical profile might contain the following VAGen environment variables: 

CS0TR0PT=2 
DB2INSTANCE=db2udb 

DPATH=/usr/l pp/vgwgs45: /usr/1 pp/vgwgs45/l ib 

EZERNLS=ENU 

EZERSQLDB=sampl e 

FCWDB2DIR=/usr/l pp/db2_G6_Gl 

FCWDBPASSWORD=vguser 

FCWDBUSER=vguser 

FCWDPATH=/u/vguser/genout 

FCWLIBPATH=/u/vguser/genout 

FCWTR0PT=31 

FCWTROUT=fcwtrace.out 

LANG=en_US 

LIBPATH=/usr/l i b : /usr/1 pp/vgwgs45/l i b 
PATH=/usr71pp/vgwgs45/bin:$PATH 

In addition, the value of EZERSQLDATE is used during generation to set the 
DB2 date and time format specified in the SQL preparation commands in 
appnameZ.SCR, the preparation command file created at this time. 

Refer to "Appendix. VisualAge Generator Environment Variables" on page 245 
for further descriptions of these environment variables. 
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Resource Association File 

If the program you are running accesses files, a resource association file must 
be created, with an entry for each serial or message queue record defined in 
the program. The resource association file is also used when your program 
contains printer maps and you want the output directed to a printer queue 
instead of the default output file (appName.map). In the AIX environment, 
the resource association file is used at run time, not at generation time. 

Creating Resource Association Files 

You can create and edit resource association files using a standard editor. You 
can enter options and values in uppercase or lowercase. All of the options can 
span lines. 

Comments are permitted and can appear anywhere in the file. Comments 
begin with the characters /* and end with the characters */. 

The default resource association file name is FCW.RSC. You can override the 
default file name by specifying the /R parameter at run time or by specifying 
a filename in the FCWRSC environment variable. For more information on 
using the /R option, see "Chapter 30. Distributing and Running C++ 
Programs on AIX" on page 161. 



The following diagram shows the syntax of the entries in the resource 
association file. 



ASSOCIATE- 


— FllE=filenamt 
p/NOREPLACE — , 


— 1 

L-/FILETYPE=-|-IBMC0B0L^ 

-MQ 

-SEQ 

-SPOOL 


— ' L/ C ontableJ 


L/noffJ 


-/REPLACE 


L/SYSNAME=sysfem resource name-^ 



■/SYSTEM=rargef system-' L_ /TEXT- 



ASSOCIATE 

Associates the file name specified in a record definition or the printer 
file with the physical file that is used for the record at run time 

FILE Specifies the file name in the record for which you are defining 
system resource association information 



Chapter 28. Customizing Your Workstation to Run C++ Programs on AIX 147 



The file name can be EZEPRINT (the print file for the program) or 
one of the file names specified for a serial, indexed, or relative record 
used by the program. 

/FILETYPE 

Specifies the implementation of the file in a target environment 

The valid file types are system-dependent. Table 17 on page 150 shows 
the valid file types for each environment. 

The file type can be one of the following: 

IBMCOBOL 

Specifies an indexed, relative, or serial file associated with a 
VSAM file on AIX. 

MQ Specifies a message queue file. 

SEQ Specifies a serial or print file associated with a system 
sequential file for the AIX environment. 

SPOOL 

Specifies a printer file. The /SYSNAME parameter specifies 
the name of the output queue. 

/CONTABLE 

Specifies a conversion table name if you want data format conversion 
to be performed on a message. The / CONTABLE entry applies only 
to files where /FILETYPE=MQ. 

If you want data format conversion to be performed on the message, 
specify a conversion table name as shown in the following example: 
/CONTABLE=conversion_tabl e_name 

If a conversion table is specified, VisualAge Generator converts the 
message from local format to remote format when the message is 
added to the queue, and from remote format to local format when the 
message is read from the queue. VisualAge Generator performs 
conversion using the message queue record structure to identify the 
data type of fields in the message. 

Specify EZECONVT for the conversion table name if you want the 
conversion table name to be picked up at run time from the 
EZECONVT special function word. 

/NOFF 

Specifies that a form feed should not be issued during Close 
processing for a map. 
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/REPLACE or /NOREPLACE 

Specifies whether an existing serial file is replaced by the new one 
that is written by the program. 

You can specify /REPLACE with file type SEQ for the AIX 
environment. If /REPLACE is specified, the first ADD to a serial file 
in a program, or the first ADD to a serial file following a CLOSE, 
adds the record to the beginning of the file. Previous file contents are 
lost. 

You can use /NOREPLACE to specify that an ADD to a file always 
appends to the end of the file. If /NOREPLACE is specified, ADD 
always adds a record to the end of the current file. /NOREPLACE is 
the default. 

/SYSNAME 

Specifies the system name of the file associated with the file name in 
the record. If /FILETYPE=SPOOL, /SYSNAME specifies an output 
queue name. If /FILETYPE=MQ, /SYSNAME specifies the queue 
manager name and queue name. 

The format of the name is system-dependent. If /FILETYPE=MQ, use 
the syntax shown in the following example: 
l$YS\\hWL=queue_mar)ager_name:queue_name 

/SYSTEM 

Specifies the target system affected by this associate command 

You might have multiple associates in one resource association file. 
The resource association used is the first association where the value 
specified for the /SYSTEM option matches the value specified for the 
/SYSTEM generation option value. 

The target system value is AIX. 

/TEXT Specifies a special type of serial file that contains line feed (LF) 

characters at the end of each line. When a record is read (SCAN), the 
LF characters are automatically removed. When a record is written 
(ADD), the LF characters are automatically appended to the end of 
each record. This option is useful when exchanging data files with 
other software packages that expect each record to be delimited with 
the LF characters. 

Example of Resource Association File Entries 

Figure 8 on page 150 shows examples of resource association file entries. 
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ASSOCIATE FI LE=FI LEI /SYSTEM=AIX /FI LETYPE=SEQ 

/SYSNAME=MY FI LE . DAT 
ASSOCIATE FI LE=EZEPRINT /SYSTEM=AIX /FILETYPE=SPOOL /SYSNAME=PRTQ1 
ASSOCIATE FI LE=EZEPRINT /FI LETYPE=SEQ /SYSNAME=PRTMAP.OUT 



Figure 8. Examples of Resource Association File Entries 



File Types Supported by Environment and Record Organization 

Table 17 shows the valid file types for the AIX environment. 

Table 17. File Types Supported by Environment and Record Organization 

Message 

System Indexed Queue Relative Serial Print 

AIX IBMCOBOL MQ IBMCOBOL IBMCOBOL SEQ 

SEQ SPOOL 
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Chapter 29. Considerations for C++ SQL Programs on AIX 



The following sections provide information for preparing and running 
programs that access relational databases: 

• Accessing DB2 Databases 

• Accessing Oracle Databases 

• Accessing Databases Using ODBC 

• Environment Variables 

• Binding an Access Plan Using DB2 

• Code Page Compatibility 

• Static Versus Dynamic SQL Statements 

• Accessing Distributed Databases 

• DB2 for AIX Version Incompatibilities 

• Oracle for AIX Version Considerations and Incompatibilities 

• Migrating Applications from Oracle 7 to Oracle 8 



Accessing DB2 Databases 

VisualAge Generator DB2 support provides direct access to DB2 databases 
without using Datajoiner or ODBC. By specifying the /DBMS=DB2 generation 
option, the VisualAge Generator program is generated specifically for DB2. 
Additional information on using DB2 is documented in the VisualAge 
Generator Design Guide. 



Accessing Oracle Databases 

VisualAge Generator Oracle support provides direct access to Oracle 
databases without using Datajoiner or ODBC. By specifying the 
/DBMS=ORACLE generation option, the VisualAge Generator program is 
generated specifically for Oracle. Additional information on using Oracle is 
documented in the VisualAge Generator Design Guide. 



Accessing Databases Using ODBC 

VisualAge Generator ODBC support provides access to a variety of relational 
databases. By specifying the /DBMS=ODBC generation option, the VisualAge 
Generator program is generated specifically for ODBC. A VisualAge Generator 
ODBC program contains dynamic SQL statements as opposed to the static 
SQL statements that are generated for DB2 and Oracle. Additional information 
on using ODBC is documented in the VisualAge Generator Design Guide. 
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Environment Variables 

The following environment variables are referenced in preparing and running 

a program containing SQL statements: 

DB2INSTANCE 

Specifies the name of the DB2 instance. (Applies to DB2 only.) 
EZERSQLDB 

Specifies the VisualAge Generator Server default database (DB2 or 
Oracle) or default data source (ODBC). 
FCWDBNAME_<progname> 

Specifies the name of the database to be used by a specific VisualAge 
Generator program (DB2, Oracle, or ODBC). 

Notes: 

1 . For DB2, the name specified is the database alias name. 

2. For Oracle, the name specified must be a service name entry in the 
tnsnames.ora file. 

3. For ODBC, the name specified must be a data source name in the 
odbc.ini file. 

EZERSQLDATE 

The value of the EZERSQLDATE environment variable during 
generation determines the DB2 date format generated for the 
precompiler step in the appnameZ.scr file. The appnameZ.scr file is 
used to make the program on the AIX system. 

ORACLE_HOME 

Specifies the directory containing the Oracle for AIX software. 

For more information on setting environment variables, see "Appendix. 
VisualAge Generator Environment Variables" on page 245. 

Binding An Access Plan Using DB2 

An access plan must be built for each DB2 database a program uses before an 
SQL program can run successfully. The process is called binding the program. 

The access plan is bound during the preparation process to the database used 
during the precompile step. Use the BIND command to bind the program to 
other databases. To use BIND, have the bind file produced during 
preparation, progname.BND, available and issue the following command under 
DB2 command line processor: 
BIND progname. BND 

Where progname. BND specifies the name of the program you want to run. 

If you do not specify a file name, the messages are directed to the standard 
output. 
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To bind an SQL program, you must have the following authority: 

• READ authority to each table the program uses 

• WRITE authority to each table the program updates 

See your database administrator to get the required authorization. 

Refer to the VisualAge Generator Generation Guide for more information on 
performing binding as part of the program generation and preparation 
process. Refer to the Database 2 for AIX Command Reference (SC09-1575) for 
more information on the BIND command. 



Code Page Compatibility 

All SQL programs that use a relational database must use the same code page. 
When you create an SQL database in DB2 for AIX, the code page of the 
process that creates the database is associated with the SQL database. 



Static Versus Dynamic SQL Statements 

When unqualified table names are used in the SQL statements of a VisualAge 
Generator program, the implicit table qualification might be different for static 
mode SQL statements than for dynamic mode SQL statements. 

In static mode, SQL statements are resolved when the program is bound. All 
unqualified SQL table names are qualified with the USERID that is logged on 
to the workstation when the bind takes place. 

In dynamic mode, SQL statements are resolved while the program is running. 
All unqualified SQL table names are qualified with the USERID that is logged 
on to the workstation where the program is running. 

Dynamic mode is used in the following situations: 

• When the Execution Time Statement Build option is specified for SQL 
statements in a generated program 

• When the table name of an SQL row record is defined as a host variable 

For more information on static mode versus dynamic mode, refer to the 

VisualAge Generator Design Guide. 



Accessing Distributed Databases 

The Distributed Database Connection Services for AIX licensed program 
provides access to any database manager enabled as a Distributed Remote 
Database Architecture (DRDA) server, including all members of the DB2 
product family. 
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The DB2 Client Program Enabler for AIX licensed program provides access to 
DB2 workstation databases, including DB2 for AIX and DB2 CAE for AIX in 
conjunction with IBM Datajoiner, provides access to non-IBM relational 
databases including Oracle and Sybase databases. 

DDCS for AIX and DB2 CAE for AIX provides the same interface for binding 
and running programs that DB2 for AIX does. Refer to these products' 
documentation for more information. 



DB2 for AIX Version Incompatibilities 

The VisualAge Generator Server for AIX DB2 interface modules, fcwmdb2.dll 
and cso40db2.dll, are very sensitive to the version of DB2 for AIX on which 
they were built versus where they execute. The DB2 interface modules were 
built on a DB2/6000 Version 2.1.2 system. If a VisualAge Generator SQL 
program is run on an AIX system with a version of DB2 for AIX at a higher 
release or maintenance level, it could receive the following message: 
FCWBG12E Load module fcwmdb2.dll cannot be loaded. The return code is 2. 

If you are running a version of DB2 for AIX at a higher release or 
maintenance level than 2.1.2 and receive message FCW0012E, use these steps 
to correct the error: 

1 . Login as root. 

2. Change to the / samples directory of the VisualAge Generator Server for 
AIX product installation directory (for example, 

/ usr / lpp / vgwgs40 / samples) . 

3. Relink fcwmdb2.dll and cso40db2.dll using the following command: 
make -f 1 inkdb2.mak 

4. Copy fcwmdb2.dll and cso40db2.dll to the /lib directory of the VisualAge 
Generator Server for AIX product installation directory (for example, 

/ usr / lpp / vgwgs40 / lib . 

If you are using Datajoiner Version 1 and receive message FCW0012E, use 
these steps to correct the error: 

1 . Login as root. 

2. Change to the /samples directory of the VisualAge Generator Server for 
AIX product installation directory (for example, 

/ usr/lpp/vgwgs40/ samples). 

3. Relink fcwmdb2.dll and cso40db2.dll using the following command: 
make -f linkdj.mak 

4. Copy fcwmdb2.sl and cso40db2.sl to the /lib directory of the VisualAge 
Generator Server for AIX product installation directory (for example, 
/usr/lpp / vgwgs40 / lib ) . 
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Oracle for AIX Version Considerations and Incompatibilities 

VisualAge Generator Server for AIX ships support for both the Oracle7 and 
Oracle8 client products and can be configured to use either one. The Oracle8 
client is used by default. The Oracle7 and Oracle8 clients cannot be used 
simultaneously. For example, you cannot use the Oracle7 client for one 
application and the Oracle8 client for another without reconfiguring 
VisualAge Generator Server for AIX in between. 

A VisualAge Generator Server tool called orasetup is provided that allows 
you to configure the version of the Oracle client that VisualAge Generator 
Server should use. The orasetup tool is located in the /samples directory of 
the VisualAge Generator Server for AIX product installation directory (for 
example, / usr/lpp/vgwgs40/ samples). 

To invoke the orasetup tool, issue the orasetup command from a command 
window within the product installation directory. The syntax is as follows: 
orasetup [ -i 7 | S ] [ -o 7 | S ] [ -fcwdir directory ] [-h|H|?] 

where 

-i Specifies the version of Oracle to change to. The default is 7. 

-o Specifies the current version of the Oracle client in use by VisualAge 
Generator Server for AIX. 

If no value is specified for this option, orasetup checks the /lib 
directory of the VisualAge Generator Server for AIX product 
installation directory for the version of the Oracle modules that are 
not currently being used. For example, if the files fcworcl7.dll and 
csoora7.dll exist in this directory, Oracle7 is not currently being used 
by VisualAge Generator Server. Hence, the current version is 8. 

-fcwdir 

Specifies the VisualAge Generator Server product installation 
directory. The default is /usr/lpp/vgwgs40. 

-h I H I ? 

Displays help information for the orasetup tool. 

When the values specified for -o and -i are different, orasetup swaps the 
current version of fcworcl.dll and csoora.dll for the specified version. 

Notes: 

1 . The FCWDBVERSION environment variable is not used on AIX. 

2. To issue the orasetup command from any command line, you must 
manually add the / samples subdirectory of the product installation 
directory to your AIX PATH statement (for example, 

/ usr / lpp / vgwgs40 / samples) . 
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For more information about the orasetup tool, see the orasetup.readme file in 
the / samples directory of the VisualAge Generator Server for AIX product 
installation directory or issue the command orasetup -h. 

The VisualAge Generator Server for AIX Oracle interface modules, fcworcl.dll 
and csoora.dll, are very sensitive to the version of Oracle for AIX on which 
they were built versus where they execute. The Oracle8 interface modules 
shipped with VisualAge Generator Server for AIX were built on an Oracle 
Version 8.0.4 system. The Oracle7 interface modules shipped with VisualAge 
Generator Server for AIX were built on an Oracle Version 7.3.4 system. If a 
VisualAge Generator SQL program is run on an AIX system with a version of 
Oracle for AIX at a higher release or maintenance level than either 7.3.4 or 
8.0.4, it could receive the following message: 

FCWBG12E Load Module fcworcl.dll cannot be loaded. The return code is 2. 

If you are running a version of Oracle for AIX at a higher release or 
maintenance level than either 7.3.4 or 8.0.4 and receive message FCW0012E, 
use these steps to correct the error: 

1 . Login as root. 

2. Ensure the ORACLE_HOME environment variable is set to point to the 
product installation directory of the version of the Oracle for AIX client 
you want to use. 

3. Change to the /samples directory of the VisualAge Generator Server for 
AIX product installation directory (for example, 

/ usr/lpp/vgwgs40/ samples). 

4. Build the VisualAge Generator Server for AIX Oracle7 modules using this 
command: 

make -f 1 i nkorcl .mak FCWDBVERSI0N=7 

Build the VisualAge Generator Server for AIX Oracle8 modules using this 

command: 

make -f 1 i nkorcl .mak 

Step 4 above builds new versions of either the VisualAge Generator Server for 
AIX Oracle7 or Oracle8 modules customized for your environment and copies 
the new fcworcl.dll and csoora.dll files to your VisualAge Generator Server for 
AIX /lib directory. The existing copies are backed up in the same directory 
and renamed with a .save extension. If you do not wish to have the makefile 
automatically install these files, follow steps 1 through 3 above and then do 
the following: 

1 . To build the VisualAge Generator Server for AIX Oracle7 modules, type 
the following command at the command prompt: 
make -f linkorcl.mak FCWDBVERSI0N=7 build 
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To build the VisualAge Generator Server for AIX Oracle8 modules, type 
the following command at the command prompt: 
make -f 1 inkorcl .mak build 

2. To install the resulting modules by hand, type the following two 
commands at the command prompt, replacing vgwgs with the path to your 
VisualAge Generator Server for AIX product installation directory (for 
example, /usr/lpp/vgwgs40): 

cp fcworcl.dll vgv/gsh i b/fcworcl .dl 1 
cp csoora.dll vgwgs H ib/csoora.dl 1 

3. To install the resulting modules using the makefile, type the following 
command at the command prompt: 

make -f 1 inkorcl .mak install 

Note: You do not need to specify FCWDBVERSION with the make 
command in this step. 

For more information about building VisualAge Generator Server for AIX 
Oracle7 and Oracle8 modules, see the linkorcl. readme file in the / samples 
directory of the VisualAge Generator Server for AIX product installation 
directory. 



Migrating Applications from Oracle 7 to Oracle 8 

If you have migrated from the Oracle7 for AIX client to the Oracle8 for AIX 
client on your AIX system, two migration paths are available for upgrading 
your VisualAge Generator applications that use the Oracle7 client library to 
use of the Oracle8 client library. Choose one of the following paths, depending 
upon the Oracle8 client/server features you plan on using: 

1 . If you do not want to use any of the new Oracle8 features or you want to 
use new Oracle8 features that do not require recoding of the application, 
relink your VisualAge Generator Oracle7 applications with the Oracle8 
client library. This allows you to take advantage of Oracle8 features such 
as Improved Data Warehouse Performance. 

A k-shell script is provided with VisualAge Generator Server to help 
automate the relink process. The script is called orarelink and is located in 
the /samples directory of your VisualAge Generator Server for AIX 
product installation directory. 

The orarelink command syntax is as follows: 

orarelink [-a] [-f filename] [appnamel appname2 ...] [-h|H|?] 

where 

-a Specifies that you would like to relink all applications in the 
current directory (determined by searching for all files named 
*z.scr). 
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-f Specifies the name of a file that contains the names of programs to 
relink in the current directory. The file should contain only one 
program name per line. Optional comment lines can be included 
by placing a pound sign (#) at the beginning of the comment line. 

appnamel appnamel ... 

Specify the names of applications (separated by a blank space) that 
you would like to relink. 

hlHI? 

Displays help information for the orarelink command. 

Notes: 

a. You can only specify applications that are in the current directory from 
which you issue the orarelink command. 

b. To issue the orarelink command from any command line, you must 
manually add the / samples subdirectory of the product installation 
directory to your AIX PATH statement (for example, 

/ usr/lpp / vgwgs40 / samples). 

c. The appname parameters are application names, not the names of the 
appnamez.scr files. For example, to relink a VisualAge Generator 
application named TEST1, you would issue the command orarelink 
TEST1. 

d. Even if you do not want to use any Oracle8 features, relinking is 
required if you want to use the Oracle8 for AIX client software with 
your VisualAge Generator applications. 

2. If you want to use new Oracle8 features that require recoding of the 
application, you must recode your VisualAge Generator applications. 
Recoding allows you to take advantage of Oracle8 features such as the 
Object Relational Technology. You must also regenerate and prepare any 
VisualAge Generator applications that you recode. 

Notes: 

1 . Oracle8 databases can be accessed using VisualAge Generator Oracle7 
applications. If you continue to use the Oracle7 client, no changes are 
necessary. Similarly, Oracle7 databases can be accessed using VisualAge 
Generator Oracle8 applications as long as the clients do not use any of the 
Object Relational Technology features of Oracle8. 

2. If you have applications that you have precompiled with the Oracle8 
precompiler, you cannot relink those applications with the Oracle7 client 
SQL library. The precompiler output is not backward compatible. 
However, applications that have been precompiled with the Oracle7 
precompiler can be relinked with the Oracle8 client SQL library. 

For more information on migrating existing Oracle7 precompiler applications 
to Oracle8 precompiler applications, refer to the documentation that came 
with your copy of the Oracle8 for AIX client. For more information about the 



158 VisualAge Generator: VisualAge Generator Server Guide for Workstation Platforms 



orarelink tool, see the orarelink.readme file in the / samples directory of the 
VisualAge Generator Server for AIX product installation directory or issue the 
command orarelink -h. 
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Chapter 30. Distributing and Running C++ Programs on 
AIX 



After the compiled program shared library files are placed in a directory on 
your system, the program is ready to be distributed and run on any 
supported system that has Visual Age Generator Server for AIX installed. To 
run your programs, VisualAge Generator provides the FCWRUN command 
with the / r and /nls options. AIX is case sensitive so you must type 
commands and parameters in the exact case specified. The FCWRUN 
command, / r and / nls options are described below. 



FCWRUN Command 

To run a generated and compiled VisualAge Generator main program, enter 
the following command: 
fcwrun progname 

Where progname is the name of the program. Do not include the All extension. 

Note: If the EZERNLS environment variable has not been set, you must 
specify the / nls parameter. 

You can only run main programs using the fcwrun command. Called 
programs can be run by a call from another VisualAge Generator program or 
a 3GL program. 



Using the /r Option 

You can use the / r optional parameter with the FCWRUN command to 
specify the name of a resource association file. If you do not specify this 
option, the default filename fcw.rsc is used. For example, if the resource 
association filename is progl.rsc, and the program name is progl, use the 
following command: 

fcwrun progl /r=progl.rsc 

The resource association file can be qualified with a path name. If it is not 
fully qualified, it will be searched for in the following locations: 

• The current directory 

• The directories specified by the FCWDPATH environment variable 

• The directories specified in the DPATH 
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You can also specify the resource association file using the FCWRSC 
environment variable. 



Using the /nls Option 

VisualAge Generator provides a /nls option to specify the language version of 
VisualAge Generator Server you want to use and the program message tables 
to use. To use this option, enter the following command: 
fcwrun mainapp /nls=xxx 

Where xxx is a valid NLS code. 

The following are the valid NLS codes for VisualAge Generator Server: 



Valid Code 


Language 


ENU 


English 


DEU 


German 


DES 


Swiss German 


ESP 


Spanish 


PTB 


Brazilian Portuguese 


KOR 


Korean 


JPN 


Japanese 


CHS 


Simplified Chinese 


CHT 


Traditional Chinese 


FRA 


French 


ITA 


Italian 



If / nls=xxx is not specified, the environment variable EZERNLS is checked. 
Either /nls=xxx or EZERNLS must be specified. 
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Part 8. Running VisualAge Generator C++ programs on 
CICS for AIX 
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Chapter 31. Preparing to Run C++ Programs on CICS for 
AIX 



After a VisualAge Generator CICS for AIX program has been generated, the 
generated objects must be moved to an AIX system and prepared before you 
can run the program. For CICS for AIX, preparation includes compiling and 
linking the generated C++ programs. The C++ Generator creates the control 
files to send the appropriate source to the remote machine and start the make 
process on that machine. 



Preparing Your CICS for AIX C++ Programs 

Preparation can be started automatically following the generate process, or it 
can be started manually with the PREPARE subcommand of HPTCMD. See 
the VisualAge Generator Generation Guide document for a list of the files 
involved in the preparation process and the syntax of the HPTCMD and 
PREPARE commands. 

Automatic Preparation 

The preparation process is automatically started by generation unless you 
specify the /NOPREP option on the generate command or did not specify 
Start preparation command file in the options notebook. 

Additionally, the following options must be specified for preparation to be 
started: 

• /DBUSER=<AIXdatabaseUserid> 

• / DBPASSWORD=< AIXdatabasePassword> 

• / DESTHOST=< AIXhostName> 

• /DESTUID=<AIXuserId> 

• / DESTPASSWORD=< AIXUserPassword> 

• /DESTDIR='<AIXDirectory>' 

Note: The AIXDirectory name must be the full path name. The user identified 
by AIXuserlD must have the following: 

• Rexec authority to the target AIX host machine 

• Write authority to the destination directory and files 

Manual Preparation 

You can run the preparation process independently from the generation 
process using the PREPARE subcommand. 
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The PREPARE subcommand can be issued only through the VisualAge 
Generator program generator command line interface. The interactive interface 
does not support the PREPARE subcommand. 

The following options are required: 

• /DBUSER=<AIXdatabaseUserid> 

• /DBPASSWORD=<AIXdatabasePassword> 

• /DESTHOST=<AIXhostName> 

• /DESTUID=<AIXuserId> 

• /DESTPASSWORD=<AIXUserPassword> 

• /DESTDIR='<AIXDirectory>' 

Note: The AIXDirectory name must be the full path name. The user identified 
by AIXuserlD must have the following: 

• Rexec authority to the target AIX host machine 

• Write authority to the destination directory and files 



Understanding Preparation Output Files 

When you compile your programs and map groups, the preparation process 
produces executable files with the extension .ibmcpp for main programs or All 
for called programs and map groups. 

In addition to these output files, you receive other files with extensions, such 
as .0, .bnd, and .tab for tables. The .0 (object) files can be deleted. Save the .bnd 
files for binding SQL programs to other databases if the program must be 
moved to other systems. 

Placing Executables 

The executables created during preparation will be in the directory specified 
in the /DESTDIR option. 

The generated table files (.tab extension) that the program uses need to be in a 
directory specified in the FCWDPATH environment variable used by the CICS 
for AIX environment file. 

Note: The user CICS must have read and execute authority to the directory. 
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Chapter 32. Customizing Your Workstation to Run C++ 
Programs on CICS for AIX 



Customizing your AIX workstation to run CICS for AIX programs require the 
following tasks be performed: 

• Setting environment variables describing the operating environment to the 
running programs 

• Defining transactions, programs, and files to CICS 

In addition, there are the optional tasks of modifying the text of VisualAge 
Generator Server for AIX messages to meet national language requirements 
and the migration of host files to the workstation. 



Setting Environment Variables 

VisualAge Generator Server for AIX provides the following environment 
variables that your system administrator can add to the CICS for AIX 
environment file (/var/cics_regions/$CICSREGION/ environment). 

Table 18. Product Specific Environment Variables for CICS for AIX 
Environment variable Runtime services 



CSOTROPT 


Optional 




CSOTROUT 


Optional 




DB2INSTANCE 


Required (if accessing 


;DB2) 


EZERJULL_xxx 


Optional 




EZERJULS_xxx 


Optional 




EZERGRGL_xxx 


Optional 




EZERGRGS_xxx 


Optional 




EZERNLS 


Required 




EZERSQLDB 


Optional 




FCWDB2DIR 


Required (if accessing 
during prep) 


; DB2) (needed 


FCWDBNOOP 


Optional 




FCWDBPASSWORD 


Required (if accessing 


;DB2) 


FCWDBUSER 


Required (if accessing 


;DB2) 


FCWDPATH 


Required 





FCWFIODB Optional 
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Table 18. Product Specific Environment Variables for CICS for AIX (continued) 


Environment variable 


Runtime services 


FCWLIBPATH 


Required 


FCWOPT 


Optional 


FCWTRDB_<tranid> 


Optional 


FCWTROPT 


Optional 


FCWTROUT 


Optional 



A typical CICS environment file might contain the following VAGen 

environment variables: 

CS0TR0PT=2 

CSOTROUT=csotrace.out 
DB2INSTANCE=db2udb 

DPATH=/usr/l pp/vgwgs45/l i b: /usr/1 pp/vgwgs45: /u/vguser/genout 

EZERNLS=ENU 

EZERSQLDB=sampl e 

FCWDBPASSWORD=vguser 

FCWDBUSER=vguser 

FCWDPATH=/u/vguser/genout 

FCWLIBPATH=/u/vguser/genout 

FCWTR0PT=31 

FCWTROUT=fcwtrace.out 

LANG=en_US 

LIBPATH=/usr/lib:/1ib:/usr/lpp/vgwgs45/lib 

In addition, the value of EZERSQLDATE is used during generation to set the 
DB2 date and time format specified in the SQL preparation commands in 
appnameZ.SCR, the preparation command file created at this time. 

Refer to "Appendix. VisualAge Generator Environment Variables" on page 245 
for further descriptions of these environment variables. 



Defining Programs to CICS for AIX 

Before a program can run in the CICS for AIX environment, the programs, 
transactions, and files must be defined to CICS for AIX as CICS resource 
definitions. Refer to the CICS Administration Reference for more complete 
information on defining resources to CICS for AIX. 

The following resource definitions are required: 

• Transaction Definitions (TDs) 

• Program Definitions (PDs) 

• File Definitions (FDs) 

• Transient Data Definitions (TDDs) 
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Sample transaction and program definitions using the cicsadd command are 
created at generation, if the CICSENTRIES=RDO generation option is 
specified. The generated command file is prognameC.SCR. This script file 
must be run manually. Before it is run, the CICS environment variable 
CICSREGION must specify the correct region name and run permission must 
be turned on by issuing the following command: 
chmod +x prognameC.scr 

Transaction Definitions 

A transaction definition is required for the following: 

• Each main program 

• Asynchronous programs you started through CREATX or specifying the RT 
generation option 

• Programs transferred to with an XFER statement 

• Programs transferred to by non-VisualAge Generator programs 

Program Definitions 

Program definitions are required for each program. The program definition 
should include at least the following attributes: 

PathName 

The directory and file name for the program executable. The file 
extension of .ibmcpp should not be included. 

File Definitions 

File definitions are required for access VSAM data set types. 

Transient Data Definition 

Transient data definitions are required for serial program files associated with 
CICS transient data queues in the resource association table. 



Migrating Host Files to CICS for AIX 

The recommended method to migrate host files to a CICS for AIX system is 
by using the CICS SFS Diagnostic Tool (cicssdt) or the CICS DB2 Diagnostic 
Tool (cicsddt) provided by CICS for AIX. This tool provides a means for 
migrating QSAM files (you can use the REPRO command to copy the contents 
of a data set from VSAM to QSAM format) from a host to SFS/DB2 on AIX. 
For more information on the cicssdt and cicsddt commands, refer to the CICS 
Administration Reference. 
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Chapter 33. Distributing C++ Programs on CICS for AIX 



You can distribute a program to multiple workstations using one of the 
following methods: 

• Individual files associated with the prepared program can be transferred to 
other workstations 

• A CICS for AIX cicsexport command can be used to combine all of the 
programs and resource definitions associated with a program into an export 
file. This export file can be transferred to other workstations and imported 
using the cicsimport command. 

VisualAge Generator tables (tablename.tab), map group dlls, and data files or 
database information are not included in the export file and must be copied 
separately. 

Refer to your CICS for AIX Administration Reference for more information on 
distributing programs using the cicsexport and cicsimport commands. 
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Chapter 34. Considerations for C++ SQL Programs on 
CICS for AIX 



The following sections provide information for preparing and running 
programs that access relational databases: 

• Accessing DB2 Databases 

• Accessing Oracle Databases 

• Environment Variables 

• Binding an Access Plan Using DB2 

• Code Page Compatibility 

• Static Versus Dynamic SQL Statements 

• Accessing Distributed Databases 

• CICS for AIX Syncpoint Coordination 

• CICS for AIX Considerations for a DB2 File System 

• Performance Considerations 

• DB2 for AIX Version Incompatibilities 

• Oracle for AIX Version Considerations and Incompatibilities 

• Migrating Applications from Oracle 7 to Oracle 8 

• SQL Programs Running Under CICS for AIX 



Accessing DB2 Databases 

VisualAge Generator DB2 support provides direct access to DB2 databases 
without using Datajoiner or ODBC. When you specify the /DBMS=DB2 
generation option, the VisualAge Generator program is generated specifically 
for DB2. Additional information on using DB2 is documented in the VisualAge 
Generator Design Guide. 



Accessing Oracle Databases 

VisualAge Generator Oracle support provides direct access to Oracle 
databases without using Datajoiner or ODBC. When you specify the 
/DBMS=ORACLE generation option, the VisualAge Generator program is 
generated specifically for Oracle. Additional information on using Oracle is 
documented in the VisualAge Generator Design Guide. 

Environment Variables 

The following environment variables are referenced in preparing and running 

a program containing SQL statements: 

DB2INSTANCE 

Specifies the name of the DB2 instance. (Applies to DB2 only.) 
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EZERSQLDB 

Specifies the VisualAge Generator Server default database (DB2 or 
Oracle). 
FCWDBNAME_<tranid> 

Specifies the name of the database (DB2 or Oracle) to be used by a 
specific VisualAge Generator Server transaction program. Tranid is the 
CICS transaction ID. 

Notes: 

1 . For DB2, the name specified is the database alias name. 

2. For Oracle, the name specified must be a service name entry in the 
tnsnames.ora file. 

FCWDBNOOP 

Specifies that CICS XA definitions are being used for database access. 
VisualAge Generator will not attempt to coordinate CICS and 
database resources but instead allows CICS to handle resource 
coordination. 

FCWTRDB_<tranid> 

The name of the relational database to be used for a specific 
transaction. <tranid> is the CICS transaction ID. 

FCWFIODB 

The name of the file system database, if CICS is set up to use a DB2 
file system. You should only specify this environment variable if the 
CICS file system and user DB2 tables are located on different 
databases. 

EZERSQLDATE 

The value of the EZERSQLDATE environment variable during 
generation determines the DB2 date format generated for the 
precompiler step in the appnameZ.scr file. The appnameZ.scr file is 
used to make the program on the AIX system. 

ORACLE_HOME 

Specifies the directory containing the Oracle software. 

For more information on setting environment variables, see "Appendix. 
VisualAge Generator Environment Variables" on page 245. 

Binding An Access Plan Using DB2 

An access plan must be built for each DB2 database a program uses before an 
SQL program can run successfully. The process is called binding the program. 

The access plan is bound during the preparation process to the database used 
during the precompile step. Use the DB2 BIND command to bind the program 
to other databases. To use the BIND command, have the bind file produced 
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during preparation, progname.BNT), available and issue the following 
command on the DB2 command line when connected to the database to 
which you want to bind the program: 
BIND progname.bnd 

where, 

progname.bnd 

Specifies the name of the bnd file for the program you want to run 

To bind an SQL program, you must have the following authority: 

• READ authority to each table the program uses 

• WRITE authority to each table the program updates 

See your database administrator to get the required authorization. 

Refer to the VisualAge Generator Generation Guide for more information on 
performing binding as part of the program generation and preparation 
process. 



Code Page Compatibility 

All SQL programs that use a relational database must use the same code page. 
When you create an SQL database in DB2 for AIX, the code page of the 
process that creates the database is associated with the SQL database. 



Static Versus Dynamic SQL Statements 

When unqualified table names are used in the SQL statements of a VisualAge 
Generator program, the implicit table qualification might be different for static 
mode SQL statements than for dynamic mode SQL statements. 

In static mode, SQL statements are resolved when the program is bound. All 
unqualified SQL table names are qualified with the USERID that is logged on 
to the workstation when the bind takes place. 

In dynamic mode, SQL statements are resolved while the program is running. 
All unqualified SQL table names are qualified with the USERID that is logged 
on to the workstation where the program is running. 

Dynamic mode is used in the following situations: 

• When the Execution Time Statement Build option is specified for SQL 
statements in a generated program 

• When the table name of an SQL row record is defined as a host variable 
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For more information on static mode versus dynamic mode, refer to the 
VisualAge Generator Design Guide. 



Accessing Distributed Databases 

The Distributed Database Connection Services for AIX licensed program 
provides access to any database manager enabled as a Distributed Remote 
Database Architecture (DRDA) server, including all members of the DB2 
product family. 

The DB2 Client Program Enabler for AIX licensed program provides access to 
DB2 workstation databases, including DB2/2 and DB2 for AIX. DB2 CAE for 
AIX in conjunction with IBM Datajoiner, provides access to non-IBM relational 
databases including Oracle and Sybase databases. 

DDCS for AIX and DB2 CAE for AIX provides the same interface for binding 
and running programs that DB2 for AIX does. Refer to these products' 
documentation for more information. 



CICS for AIX SYNCPOINT Coordination 

By default, CICS for AIX coordinates commit and rollback of resources 
between CICS and the database manager by sequentially issuing a DB2 
commit/ rollback, followed by a CICS syncpoint syncpoint/ rollback. If you are 
using XA support, it is necessary that your system is set up to send a message 
to VisualAge Generator indicating that CICS is coordinating commit and 
rollback between CICS and the database manager. To set up this message link, 
set the FCWDBNOOP environment variable. This will indicate to VisualAge 
Generator not to attempt a DB2 commit / rollback at the end of the unit of 
work. 



CICS for AIX Considerations for a DB2 File System 

If you have setup CICS to use a DB2 file system versus a SFS file system, then 
you need to take into consideration how this affects your VisualAge Generator 
program. By default, the connection pointing to your DB2 file system that was 
established by CICS will be the active connection. If all of your user tables are 
also on this database, you do not need to worry about switching connections 
to your user databases. This means that you do not need to set the 
FCWFIODB, EZERSQLDB, and FCWTRDB_<tranid> environment variables. 

If your user data is on a different database, the user needs to ensure that the 
database connection is active before using the database. It is recommended 
that you have VisualAge Generator handle switching of the connections from 
dormant to active. VisualAge Generator will handle the switching of 
connections, if the following environment variables are set: 
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FCWFI0DB=DB2 filesystem name 
EZERSQLDB=user database name 
FCWTRDB_<tranid>=user database name 

When you start CICS, the DB2 file system database connection will be active 
and all other connections will be dormant. When VisualAge Generator 
attempts a database I/O, VisualAge Generator will set the user database 
connection active, perform the database I/O, and set the DB2 file system 
connection active. VisualAge Generator first uses FCWTRDB_<tranid>, if it is 
available. If not available, VisualAge Generator then uses EZERSQLDB for the 
user database name. 

VisualAge Generator uses temporary storage queues when performing 
printing operations. If you submit multiple, large print jobs, this might cause 
the DB2 file system to lock. 

Performance Considerations 

Refer to the CICS for AIX and DB2 for AIX documentation for more 
information on temporary storage queues when using DB2 as a file system. 

DB2 for AIX Version Incompatibilities 

The VisualAge Generator Server for AIX DB2 interface modules, fcwmdb2.dll 
and cso40db2.dll, are very sensitive to the version of DB2 for AIX on which 
they were built versus where they execute. The DB2 interface modules were 
built on a DB2/6000 Version 2.1.2 system. If a VisualAge Generator SQL 
program is run on an AIX system with a version of DB2 for AIX at a higher 
release or maintenance level, it could receive the following message: 
FCWGB12E Load module fcwmdb2.dll cannot be loaded. The return code is 2. 

If you are running a version of DB2 for AIX at a higher release or 
maintenance level than 2.1.2 and receive message FCW0012E, use these steps 
to correct the error: 

1 . Login as root. 

2. Change to the / samples dierectory of the VisualAge Generator Server for 
AIX product installation directory (for 

example,/ usr /lpp / vgwgs40 / samples). 

3. Relink fcwmdb2.dll and cso40db2.dll using the following command: 
make -f 1 inkdb2.mak 

4. Copy fcwmdb2.dll and cso40db2.dll to the /lib directory of the VisualAge 
Generator Server for AIX product installation directory (for example, 

/ usr / lpp / vgwgs40 / lib ) . 
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If you are using Datajoiner Version 1 and receive message FCW0012E, use 
these steps to correct the error: 

1 . Login as root. 

2. Change to the /samples directory of the Visual Age Generator Server for 
AIX product installation directory (for example, 

/ usr / lpp / vgwgs40 / samples) . 

3. Relink fcwmdb2.dll and cso40db2.dll using the following command: 
make -f 1 i nkdj .mak 

4. Copy fcwmdb2.dll and cso40db2.dll to the /lib directory of the VisualAge 
Generator Server for AIX product installation directory (for example, 
/usr / lpp / vgwgs40/ lib) . 



Oracle for AIX Version Considerations and Incompatibilities 

VisualAge Generator Server for AIX ships support for both the Oracle7 and 
Oracle8 client products and can be configured to use either one. The Oracle8 
client is used by default. The Oracle7 and Oracle8 clients cannot be used 
simultaneously. For example, you cannot use the Oracle7 client for one 
application and the Oracle8 client for another without reconfiguring 
VisualAge Generator Server for AIX in between. 

A VisualAge Generator Server tool called orasetup is provided that allows 
you to configure the version of the Oracle client that VisualAge Generator 
Server should use. The orasetup tool is located in the / samples directory of 
the VisualAge Generator Server for AIX product installation directory (for 
example, / usr / lpp / vgwgs40 / samples) . 

To invoke the orasetup tool, issue the orasetup command from a command 
window within the product installation directory. The syntax is as follows: 
orasetup [ -i 7 | S ] [ -o 7 | 8 ] [ -fcwdir directory ] [-h|H|?] 

where 

-i Specifies the version of Oracle to change to. The default is 7. 

-o Specifies the current version of the Oracle client in use by VisualAge 
Generator Server for AIX. 

If no value is specified for this option, orasetup checks the /lib 
directory of the VisualAge Generator Server for AIX product 
installation directory for version of the Oracle modules that are not 
currently being used. For example, if the files fcworcl7.dll and 
csoora7.dll exist in this directory, Oracle7 is not currently being used 
by VisualAge Generator Server. Hence, the current version is 8. 
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-fcwdir 

Specifies the VisualAge Generator Server product installation 
directory. The default is /usr/lpp/vgwgs40. 

-h I H I ? 

Displays help information for the orasetup tool. 

When the values specified for -o and -i are different, orasetup swaps the 
current version of fcworcl.dll and csoora.dll for the specified version. 

Notes: 

1 . The FCWDBVERSION environment variable is not used on AIX. 

2. To issue the orasetup command from any command line, you must 
manually add the / samples subdirectory of the product installation 
directory to your AIX PATH statement (for example, 

/ usr /lpp / vgwgs40 / samples). 

For more information about the orasetup tool, see the orasetup.readme file in 
the / samples directory of the VisualAge Generator Server for AIX product 
installation directory or issue the command orasetup -h. 

The VisualAge Generator Server for AIX Oracle interface modules, fcworcl.dll 
and csoora.dll, are very sensitive to the version of Oracle for AIX on which 
they were built versus where they execute. The Oracle8 interface modules 
shipped with VisualAge Generator Server for AIX were built on an Oracle 
Version 8.0.4 system. The Oracle7 interface modules shipped with VisualAge 
Generator Server for AIX were built on an Oracle Version 7.3.4 system. If a 
VisualAge Generator SQL program is run on an AIX system with a version of 
Oracle for AIX at a higher release or maintenance level than either 7.3.4 or 
8.0.4, it could receive the following message: 

FCW0612E Load Module fcworcl.dll cannot be loaded. The return code is 2. 

If you are running a version of Oracle for AIX at a higher release or 
maintenance level than either 7.3.4 or 8.0.4 and receive message FCW0012E, 
use these steps to correct the error: 

1 . Login as root. 

2. Ensure the ORACLE_HOME environment variable is set to point to the 
product installation directory of the version of the Oracle for AIX client 
you want to use. 

3. Change to the /samples directory of the VisualAge Generator Server for 
AIX product installation directory (for example, 

/ usr / lpp / vgwgs40 / samples) . 

4. Build the VisualAge Generator Server for AIX Oracle7 modules using this 
command: 

make -f 1 inkorcl .mak FCWDBVERSI0N=7 
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Build the VisualAge Generator Server for AIX Oracle8 modules using this 
command: 

make -f 1 i nkorcl .mak 

Step 4 above builds new versions of either the VisualAge Generator Server for 
AIX Oracle7 or Oracle8 modules customized for your environment and copies 
the new fcworcl.dll and csoora.dll files to your VisualAge Generator Server for 
AIX /lib directory. The existing copies are backed up in the same directory 
and renamed with a .save extension. If you do not wish to have the makefile 
automatically install these files, follow steps 1 through 3 above and then do 
the following: 

1 . To build the VisualAge Generator Server for AIX Oracle7 modules, type 
the following command at the command prompt: 

make -f li nkorcl .mak FCWDBVERSI0M=7 build 

To build the VisualAge Generator Server for AIX Oracle8 modules, type 
the following command at the command prompt: 
make -f li nkorcl .mak build 

2. To install the resulting modules by hand, type the following two 
commands at the command prompt, replacing vgwgs with the path to your 
VisualAge Generator Server for AIX product installation directory (for 
example, /usr/lpp/vgwgs40): 

cp fcworcl.dll vgwgs/] ib/fcworcl .dl 1 
cp csoora.dll ygwgs/lib/csoora.dll 

3. To install the resulting modules using the makefile, type the following 
command at the command prompt: 

make -f linkorcl.mak install 

Note: You do not need to specify FCWDBVERSION with the make 
command in this step. 

For more information about building VisualAge Generator Server for AIX 
Oracle7 and Oracle8 modules, see the linkorcl.readme file in the / samples 
directory of the VisualAge Generator Server for AIX product installation 
directory. 



Migrating Applications from Oracle 7 to Oracle 8 

If you have migrated from the Oracle7 for AIX client to the Oracle8 for AIX 
client on your AIX system, two migration paths are available for upgrading 
your VisualAge Generator applications that use the Oracle7 client library to 
use of the Oracle8 client library. Choose one of the following paths, depending 
upon the Oracle8 client /server features you plan on using: 
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1 . If you do not want to use any of the new Oracle8 features or you want to 
use new Oracle8 features that do not require recoding of the application, 
relink your VisualAge Generator Oracle7 applications with the Oracle8 
client library. This allows you to take advantage of Oracle8 features such 
as Improved Data Warehouse Performance. 

A k-shell script is provided with VisualAge Generator Server to help 
automate the relink process. The script is called orarelink and is located in 
the / samples directory of your VisualAge Generator Server for AIX 
product installation directory. 

The orarelink command syntax is as follows: 

orarelink [-a] [-f filename] [appnamel appname2 ...] [-h[H|?] 

where 

-a Specifies that you would like to relink all applications in the 
current directory (determined by searching for all files named 
*z.scr). 

-f Specifies the name of a file that contains the names of programs to 
relink in the current directory. The file should contain only one 
program name per line. Optional comment lines can be included 
by placing a pound sign (#) at the beginning of the comment line. 

appnamel appnamel ... 

Specify the names of applications (separated by a blank space) that 
you would like to relink. 

hlHI? 

Displays help information for the orarelink command. 

Notes: 

a. You can only specify applications that are in the current directory from 
which you issue the orarelink command. 

b. To issue the orarelink command from any command line, you must 
manually add the / samples subdirectory of the product installation 
directory to your AIX PATH statement (for example, 

/ usr / lpp / vgwgs40 / samples) . 

c. The appname parameters are application names, not the names of the 
appnamez.scr files. For example, to relink a VisualAge Generator 
application named TEST1, you would issue the command orarelink 
TEST1. 

d. Even if you do not want to use any Oracle8 features, relinking is 
required if you want to use the Oracle8 for AIX client software with 
your VisualAge Generator applications. 

2. If you want to use new Oracle8 features that require recoding of the 
application, you must recode your VisualAge Generator applications. 
Recoding allows you to take advantage of Oracle8 features such as the 
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Object Relational Technology. You must also regenerate and prepare any 
VisualAge Generator applications that you recode. 

Notes: 

1 . Oracle8 databases can be accessed using VisualAge Generator Oracle7 
applications. If you continue to use the Oracle7 client, no changes are 
necessary. Similarly Oracle7 databases can be accessed using VisualAge 
Generator Oracle8 applications as long as the clients do not use any of the 
Object Relational Technology features of Oracle8. 

2. If you have applications that you have precompiled with the Oracle8 
precompiler, you cannot relink those applications with the Oracle7 client 
SQL library. The precompiler output is not backward compatible. 
However, applications that have been precompiled with the Oracle7 
precompiler can be relinked with the Oracle8 client SQL library. 

For more information on migrating existing Oracle7 precompiler applications 
to Oracle8 precompiler applications, refer to the documentation that came 
with your copy of the Oracle8 for AIX client. For more information about the 
orarelink tool, see the orarelink.readme file in the / samples directory of the 
VisualAge Generator Server for AIX product installation directory or issue the 
command orarelink -h. 



SQL Programs Running Under CICS for AIX 

If you are running AIX 4.1 and you do not have CICS for AIX installed, you 
will need to complete the following steps. The VisualAge Generator Server for 
AIX DB2 interface modules, fcwmdb2.dll and cso31db2.dll, were linked with 
db2.o instead of libdb2.a to facilitate running with XA enabled databases. If 
CICS for AIX is installed, there should already be a file named db2.o in 
/usr/lpp/db2_02_01/lib and a symbolic link from /usr/lib. See the CICS for 
AIX Administration Guide for more information. If db2.o does not exist, do the 
following: 

1 . Login as root. 

2. Add a symbolic link for db2.o using the following command: 
In -s /usr71pp/db2_02_01/lib/db2.o /usr/1 ib/db2.o 

3. Create the DB2 shared object using the following command: 

cd /usr/1 pp/db2_B2_01/lib 
ar -vx 1 ibdb2.a 
mv shr.o db2.o 

Note: The DB2 directory name used above will vary depending on the 
version of DB2 installed. 



182 VisualAge Generator: VisualAge Generator Server Guide for Workstation Platforms 



Chapter 35. Running C++ Programs on CICS for AIX 



To run an program under CICS for AIX you must first start a CICS for AIX 
terminal with the cicsterm command for 3270 terminals or with the cicstermp 
command for printers. 

Refer to the CICS Administration Reference for more information about these 
commands. 

Refer to your CICS for AIX documentation for other methods for starting 
transactions. 
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Part 9. Running VisualAge Generator C++ programs on 
Solaris 
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Chapter 36. Preparing to Run C++ Programs on Solaris 



After a VisualAge Generator Solaris program has been generated, the 
generated objects must be moved to a Solaris system and prepared before you 
can run the program. For Solaris, preparation includes compiling and linking 
generated C++ programs. The C++ Generator creates the control files to send 
the appropriate source to the remote machine and start the make process on 
that machine. 

Preparation can be started automatically following the generate process, or it 
can be started manually with the Prepare subcommand of HPTCMD. 



Automatic Preparation 

The preparation process is automatically started by generation unless you 
specify the /NOPREP option on the generate command or did not specify 
Start preparation command file in the options notebook. 

Additionally, the following options must be specified for preparation to be 
started: 

• /DBUSER=<SolarisDatabaseUserid> — if using DB2 or Oracle 

• /DBPASSWORD=<SolarisDatabasePassword> — if using DB2 or Oracle 

• /DESTHOST=<SolarisHostName> 

• /DESTUID=<SolarisUserId> 

• /DESTPASSWORD=<SolarisUserPassword> 

• /DESTDIR='<SolarisDirectory>' 

Note: The directory must be contained within single quotes and should be the 
full path name. The user must have the following: 

• rexec authority to the target Solaris host machine 

• write authority to the destination directory and files 

Manual Preparation 

You can run the preparation process independently from the generation 
process using the PREPARE subcommand. 

The PREPARE subcommand can be issued only through the VisualAge 
Generator program generator command line interface. The interactive interface 
does not support the PREPARE subcommand. 

The following options are required: 

• /DBUSER=<SolarisDatabaseUserid> — if using DB2 or Oracle 
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• /DBPASSWORD=<SolarisDatabasePassword> — if using DB2 or Oracle 

• /DESTHOST=<SolarisHostName> 

• /DESTUID=<SolarisUserId> 

• /DESTPASSWORD=<SolarisUserPassword> 

• /DESTDIR='<SolarisDirectory>' 

The preparation process in the Solaris environment involves transferring the 
source objects (generated source, generated tables, and generated program 
specific utilities) to the target Solaris host machine, and remotely invoking the 
compiler and linker on that machine. 

The program can then be run at the target Solaris machine, by using the 
following command: 
fcwrun progName 



Generation Output Files 

The output files created at generation are placed in the generation output 
directory or the current directory if the / GENOUT option is not specified. See 
the VisualAge Generator Generation Guide for a list of these files and how to 
generate them. 



Understanding Compiled Output Files 

The outputs you receive from program preparation are shared object libraries 
(SOs) which, along with the .TAB files for tables, constitute the executable 
code for the program. The following SOs are created for each program: 

progname.cpp 

progname is the name of a main program 

progcall.so 

progcall is the name of a called program 

map.so 

map is the name of the main map group 
hip. so hip is the name of the help map group 

The map.so and hip. so are created only if a map group or help map group is 
defined for the program. 

In addition to the xpp and .so output files, you will receive other files with 
extensions such as .0 and .bnd. The .0 (object) files can be deleted. The .bnd file 
should be saved for binding SQL programs to other databases, if the program 
must be moved to other systems. All the other files are temporary files and 
can be deleted. 
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Placing Shared Libraries 

The shared libraries created during preparation will be in the directory 
specified in the /DESTDIR generation option. This directory must be in the 
path defined in the LD_LIBRARY_PATH environment variable. 
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Chapter 37. Customizing Your Workstation to Run C++ 
Programs on Solaris 

This chapter describes the tasks that need to be performed to set up the 
workstation to run Solaris programs. These tasks include the following 
program preparation steps: 

• Setting environment variables 

• Creating a resource association file 

Before you can run your programs, you need to set the required environment 
variables for the system. 

If you want to distribute C++ generated programs to other Solaris systems, 
you need to set the environment variables on those systems too. 



Defining the Environment Variables 

VisualAge Generator Server provides the following environment variables that 
you can add to your .profile or you can set them from the Solaris command 
line when setting up your environment to run programs. 

You must consider all the Solaris environment variables when configuring 
your workstation to run Solaris programs. Table 19 shows the product-specific 
environment variables that can be customized for Solaris. 

Table 19. Product Specific Environment Variables for Solaris 
Environment variable Solaris runtime 



CSOTROPT 


Optional 


CSOTROUT 


Optional 


DB2INSTANCE 


Required 


EZEGRGL_xxx 


Optional 


EZEGRGS_xxx 


Optional 


EZEJULL_xxx 


Optional 


EZEJULS_xxx 


Optional 


EZERNLS 


Required 


EZERSQLDB 


Optional 


FCWDB2DIR 


Required (if accessing DB2 Solaris) 


FCWDBNAME_<progname> 


Optional 
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Table 19. Product Specific Environment Variables for Solaris (continued) 



Environment variable Solaris runtime 



FCWDBPASSWORD 


Optional 


FCWDBUSER 


Optional 


FCWDPATH 


Optional 


FCWLIBPATH 


Optional 


FCWRSC 


Optional 


FCWOPT 


Optional 


FCWTROPT 


Optional 


FCWTROUT 


Optional 


ORACLE_HOME 


Optional 


PATH 


Required 


LD_LIBRARY_PATH 


Required 



A typical profile might contain the following VAGen environment variables: 
CS0TR0PT=2 

CSOTROUT=csotrace.out 

DB2INSTANCE=db2inst6 

DPATH=/opt/vgwgs45 : /opt/vgwgs45/l i b 

EZERNLS=ENU 

EZERSQLDB=sampl e 

FCWDB2DIR=/opt/IBMdb2/V6. 1 

FCWDBPASSWORD=vguser 

FCWDBUSER=vguser 

FCWDPATH=/home/vguser/genout 

FCWLIBPATH=/home/vguser7genout 

FCWTR0PT=31 

FCWTROUT=fcwtrace.out 

LANG=en_US 

LD_LIBRARY_PATH=/opt/vgwgs45/l i b : /home/prof fer/genout : $ LD_LI BRARY_PATH 
PATH=/opt/vgwgs45/bi n : $PATH 

In addition, the value of EZERSQLDATE (on the generation machine) is used 
during generation to set the DB2 date and time format. 

Refer to "Appendix. VisualAge Generator Environment Variables" on page 245 
for further descriptions of these environment variables. 
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Resource Association File 

If the program you are running accesses files, a resource association file must 
be created, with an entry for each serial or message queue record defined in 
the program. The resource association file is also used when your program 
contains printer maps and you want the output directed to a printer queue 
instead of the default output file (appName.map). In the Solaris environment, 
the resource association file is used at run time, not at generation time. 

Creating Resource Association Files 

You can create and edit resource association files using a standard editor. You 
can enter options and values in uppercase or lowercase. All of the options can 
span lines. 

Comments are permitted and can appear anywhere in the file. Comments 
begin with the characters /* and end with the characters */. 

The default resource association file name is FCW.RSC. You can override the 
default file name by specifying the /R parameter at run time or by specifying 
a filename in the FCWRSC environment variable. For more information on 
using the /R option, see "Chapter 39. Distributing and Running C++ 
Programs on Solaris" on page 205. 

The following diagram shows the syntax of the entries in the resource 
association file. 

►» — ASSOCIATE — FILE=/i lename- 



LETYPE= 



-MQ 

-SEQ — 
-SP00L- 



L/contableJ L/nofF- 



-/NOREPLACE- 



-/REPLACE- 



L/SYSNAME=system resource name-^ \—/SYSTEV\=target system- 



L/textJ 



ASSOCIATE 

Associates the file name specified in a record definition or the printer 
file with the physical file that is used for the record at run time 

FILE Specifies the file name in the record for which you are defining 
system resource association information 
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The file name can be EZEPRINT (the print file for the program) or 
one of the file names specified for a serial, indexed, or relative record 
used by the program. 

/FILETYPE 

Specifies the implementation of the file in a target environment 

The valid file types are system-dependent. Table 20 on page 196 shows 
the valid file types for each environment. 

The file type can be one of the following: 

MQ Specifies a message queue file. 

SEQ Specifies a serial or print file associated with a system 
sequential file for the Solaris environment. 

SPOOL 

Specifies a printer file. The /SYSNAME parameter specifies 
the name of the output queue. 

/CONTABLE 

Specifies a conversion table name if you want data format conversion 
to be performed on a message. The / CONTABLE entry applies only 
to files where /FILETYPE=MQ. 

If you want data format conversion to be performed on the message, 
specify a conversion table name as shown in the following example: 
/CONTABLE=conversion_tabl e_name 

If a conversion table is specified, VisualAge Generator converts the 
message from local format to remote format when the message is 
added to the queue, and from remote format to local format when the 
message is read from the queue. VisualAge Generator performs 
conversion using the message queue record structure to identify the 
data type of fields in the message. 

Specify EZECONVT for the conversion table name if you want the 
conversion table name to be picked up at run time from the 
EZECONVT special function word. 

/NOFF 

Specifies that a form feed should not be issued during Close 
processing for a map. 

/REPLACE or /NOREPLACE 

Specifies whether an existing serial file is replaced by the new one 
that is written by the program. 

You can specify /REPLACE with file type SEQ for the Solaris 
environment. If /REPLACE is specified, the first ADD to a serial file 
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in a program, or the first ADD to a serial file following a CLOSE, 
adds the record to the beginning of the file. Previous file contents are 
lost. 

You can use /NOREPLACE to specify that an ADD to a file always 
appends to the end of the file. If /NOREPLACE is specified, ADD 
always adds a record to the end of the current file. /NOREPLACE is 
the default. 

/SYSNAME 

Specifies the system name of the file associated with the file name in 
the record. If /FILETYPE=SPOOL, /SYSNAME specifies an output 
queue name. If /FILETYPE=MQ, /SYSNAME specifies the queue 
manager name and queue name. 

The format of the name is system-dependent. If /FILETYPE=MQ, use 
the syntax shown in the following example: 
/SYSN/\ME=queue_manager_name:queue_naiTie 

/SYSTEM 

Specifies the target system affected by this associate command 

You might have multiple associates in one resource association file. 
The resource association used is the first association where the value 
specified for the /SYSTEM option matches the value specified for the 
/SYSTEM generation option value. 

The target system value is SOLARIS. 

/TEXT Specifies a special type of serial file that contains line feed (LF) 

characters at the end of each line. When a record is read (SCAN), the 
LF characters are automatically removed. When a record is written 
(ADD), the LF characters are automatically appended to the end of 
each record. This option is useful when exchanging data files with 
other software packages that expect each record to be delimited with 
the LF characters. 

Example of Resource Association File Entries 

Figure 9 shows examples of resource association file entries. 

ASSOCIATE FI LE=FI LEI /SYSTEM=SOLARIS /FI LETYPE=SEQ 

/SYSNAME=MYFILE.DAT 
ASSOCIATE FILE=EZEPRINT /SYSTEM=SOLARIS /FI LETYPE=SP00L /SYSNAME=PRTQ1 
ASSOCIATE FILE=EZEPRINT /FI LETYPE=SEQ /SYSNAME=PRTMAP . OUT 



Figure 9. Examples of Resource Association File Entries 
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File Types Supported by Environment and Record Organization 

Table 20 shows the valid file types for the Solaris environment. 

Table 20. File Types Supported by Environment and Record Organization 

Message 

System Indexed Queue Relative Serial Print 

Solaris N/A MQ N/A SEQ SEQ 

SPOOL 
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Chapter 38. Considerations for C++ SQL Programs on 
Solaris 



The following sections provide information for preparing and running 
programs that access relational databases: 

• Accessing DB2 Databases 

• Accessing Oracle Databases 

• Accessing Databases Using ODBC 

• Environment Variables 

• Binding an Access Plan Using DB2 

• Code Page Compatibility 

• Static Versus Dynamic SQL Statements 

• Accessing Distributed Databases 

• DB2 for Solaris Version Incompatibilities 

• Oracle for Solaris Version Considerations and Incompatibilities 

• Migrating Applications from Oracle 7 to Oracle 8 



Accessing DB2 Databases 

VisualAge Generator DB2 support provides direct access to DB2 databases 
without using Datajoiner or ODBC. By specifying the /DBMS=DB2 generation 
option, the VisualAge Generator program is generated specifically for DB2. 
Additional information on using DB2 is documented in the VisualAge 
Generator Design Guide. 



Accessing Oracle Databases 

VisualAge Generator Oracle support provides direct access to Oracle 
databases without using Datajoiner or ODBC. By specifying the 
/DBMS=ORACLE generation option, the VisualAge Generator program is 
generated specifically for Oracle. Additional information on using Oracle is 
documented in the VisualAge Generator Design Guide. 



Accessing Databases Using ODBC 

VisualAge Generator ODBC support provides access to a variety of relational 
databases. By specifying the /DBMS=ODBC generation option, the VisualAge 
Generator program is generated specifically for ODBC. A VisualAge Generator 
ODBC program contains dynamic SQL statements as opposed to the static 
SQL statements that are generated for DB2 and Oracle. Additional information 
on using ODBC is documented in the VisualAge Generator Design Guide. 
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Environment Variables 

The following environment variables are referenced in preparing and running 

a program containing SQL statements: 

DB2INSTANCE 

Specifies the name of the DB2 instance. (Applies to DB2 only.) 
EZERSQLDB 

Specifies the VisualAge Generator Server default database (DB2, 
Oracle, or ODBC). 
FCWDBNAME_<progname> 

Specifies the name of the database to be used by a specific VisualAge 
Generator program (DB2, Oracle, or ODBC). 

Notes: 

1 . For DB2, the name specified is the database alias name. 

2. For Oracle, the name specified must be a service name entry in the 
tnsnames.ora file. 

3. For ODBC, the name specified must be an entry in the odbc.ini 
file. 

EZERSQLDATE 

The value of the EZERSQLDATE environment variable during 
generation determines the DB2 date format generated for the 
precompiler step in the appnameZ.scr file. The appnameZ.scr file is 
used to make the program on the Solaris system. 
ORACLE_HOME 

Specifies the directory containing the Oracle for Solaris software. 

For more information on setting environment variables, see "Appendix. 
VisualAge Generator Environment Variables" on page 245. 

Binding An Access Plan Using DB2 

An access plan must be built for each DB2 database a program uses before an 
SQL program can run successfully. The process is called binding the program. 

The access plan is bound during the preparation process to the database used 
during the precompile step. Use the BIND command to bind the program to 
other databases. To use BIND, have the bind file produced during 
preparation, progname.BNT), available and issue the following command under 
the DB2 command line processor: 
BIND progname. BND 

Where progname. BND specifies the name of the program you want to run. 

If you do not specify a file name, the messages are directed to the standard 
output. 
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To bind an SQL program, you must have the following authority: 

• READ authority to each table the program uses 

• WRITE authority to each table the program updates 

See your database administrator to get the required authorization. 

Refer to the VisualAge Generator Generation Guide for more information on 
performing binding as part of the program generation and preparation 
process. Refer to the IBM DB2 Command Reference for more information on the 
BIND command. 



Code Page Compatibility 

All SQL programs that use a relational database must use the same code page. 
When you create an SQL database in DB2 for Solaris, the code page of the 
process that creates the database is associated with the SQL database. 



Static Versus Dynamic SQL Statements 

When unqualified table names are used in the SQL statements of a VisualAge 
Generator program, the implicit table qualification might be different for static 
mode SQL statements than for dynamic mode SQL statements. 

In static mode, SQL statements are resolved when the program is bound. All 
unqualified SQL table names are qualified with the USERID that is logged on 
to the workstation when the bind takes place. 

In dynamic mode, SQL statements are resolved while the program is running. 
All unqualified SQL table names are qualified with the USERID that is logged 
on to the workstation where the program is running. 

Dynamic mode is used in the following situations: 

• When the Execution Time Statement Build option is specified for SQL 
statements in a generated program 

• When the table name of an SQL row record is defined as a host variable 

For more information on static mode versus dynamic mode, refer to the 

VisualAge Generator Design Guide. 



Accessing Distributed Databases 

The Distributed Database Connection Services for Solaris licensed program 
provides access to any database manager enabled as a Distributed Remote 
Database Architecture (DRDA) server, including all members of the DB2 
product family. 
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The DB2 Client Program Enabler for Solaris licensed program provides access 
to DB2 workstation databases, including DB2 and DB2 CAE for Solaris, 
provides access to non-IBM relational databases including Oracle and Sybase 
databases. 

DDCS for Solaris and DB2 CAE for Solaris provides the same interface for 
binding and running programs that DB2 does. Refer to these products' 
documentation for more information. 



Oracle for Solaris Version Considerations and Incompatibilities 

VisualAge Generator Server for Solaris ships support for both the Oracle7 and 
Oracle8 client products and can be configured to use either one. The Oracle8 
client is used by default. The Oracle7 and Oracle8 clients cannot be used 
simultaneously. For example, you cannot use the Oracle7 client for one 
application and the Oracle8 client for another without reconfiguring 
VisualAge Generator Server for Solaris in between. 

A VisualAge Generator Server tool called orasetup is provided that allows 
you to configure the version of the Oracle client that VisualAge Generator 
Server should use. The orasetup tool is located in the / samples directory of 
the VisualAge Generator Server for Solaris product installation directory (for 
example, / opt/ vgwgs40/ samples). 

To invoke the orasetup tool, issue the orasetup command from a command 
window within the product installation directory. The syntax is as follows: 
orasetup [ -i 7 | S ] [ -o 7 | 8 ] [ -fcwdir directory ] [-h|H|?] 

where 

-i Specifies the version of Oracle to change to. The default is 7. 

-o Specifies the current version of the Oracle client in use by VisualAge 
Generator Server for Solaris. 

If no value is specified for this option, orasetup checks the /lib 
directory of the VisualAge Generator Server for Solaris product 
installation directory for the version of the Oracle modules that are 
not currently being used. For example, if the files fcworcl7.so and 
csoora7.so exist in this directory, Oracle7 is not currently being used 
by VisualAge Generator Server. Hence, the current version is 8. 

-fcwdir 

Specifies the VisualAge Generator Server product installation 
directory. The default is /opt/vgwgs40. 

-h I H I ? 

Displays help information for the orasetup tool. 
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When the values specified for -o and -i are different, orasetup swaps the 
current version of fcworcl.so and csoora.so for the specified version. 

Note: 
Notes: 

1 . The FCWDBVERSION environment variable is not used on Solaris. 

2. To issue the orasetup command from any command line, you must 
manually add the / samples subdirectory of the product installation 
directory to your Solaris PATH statement (for example, 

/ opt / vgwgs40 / samples) . 

For more information about the orasetup tool, see the orasetup.readme file in 
the / samples directory of the VisualAge Generator Server for Solaris product 
installation directory or issue the command orasetup -h. 

The VisualAge Generator Server for Solaris Oracle interface modules, 
fcworcl.so and csoora.so, are very sensitive to the version of Oracle for Solaris 
on which they were built versus where they execute. The Oracle8 interface 
modules shipped with VisualAge Generator Server for Solaris were built on 
an Oracle Version 8.0.4 system. The Oracle7 interface modules shipped with 
VisualAge Generator Server for Solaris were built on an Oracle Version 7.3.4 
system. If a VisualAge Generator SQL program is rim on a Solaris system 
with a version of Oracle for Solaris at a higher release or maintenance level 
than either 7.3.4 or 8.0.4, it could receive the following message: 
FCWGB12E Load Module fcworcl.so cannot be loaded. The return code is 2. 

If you are running a version of Oracle for Solaris at a higher release or 
maintenance level than either 7.3.4 or 8.0.4 and receive message FCW0012E, 
use these steps to correct the error: 

1 . Login as root. 

2. Ensure the ORACLE_HOME environment variable is set to point to the 
product installation directory of the version of the Oracle for Solaris client 
you want to use. 

3. Change to the / samples directory of the VisualAge Generator Server for 
Solaris product installation directory (for example, 

/ opt/vgwgs40/ samples). 

4. Build the VisualAge Generator Server for Solaris Oracle7 modules using 
this command: 

make -f 1 inkorcl .mak FCWDBVERSI0N=7 

Build the VisualAge Generator Server for Solaris Oracle8 modules using 
this command: 
make -f 1 inkorcl .mak 
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Step 4 above builds new versions of either the VisualAge Generator Server for 
Solaris Oracle7 or Oracle8 modules customized for your environment and 
copies the new fcworcl.so and csoora.so files to your VisualAge Generator 
Server for Solaris /lib directory. The existing copies are backed up in the same 
directory and renamed with a .save extension. If you do not wish to have the 
makefile automatically install these files, follow steps 1 through 3 above and 
then do the following: 

1 . To build the VisualAge Generator Server for Solaris Oracle7 modules, type 
the following command at the command prompt: 

make -f linkorcl .mak FCWDBVERSI0N=7 build 

To build the VisualAge Generator Server for Solaris Oracle8 modules, type 
the following command at the command prompt: 
make -f linkorcl .mak build 

2. To install the resulting modules by hand, type the following two 
commands at the command prompt, replacing vgwgs with the path to your 
VisualAge Generator Server for Solaris product installation directory (for 
example, / opt / vgwgs40) : 

cp fcworcl.so vgwgs H ib/fcworcl .so 
cp csoora.so ygwgs/lib/csoora.so 

3. To install the resulting modules using the makefile, type the following 
command at the command prompt: 

make -f linkorcl .mak install 

Note: You do not need to specify FCWDBVERSION with the make 
command in this step. 

For more information about building VisualAge Generator Server for Solaris 
Oracle7 and Oracle8 modules, see the linkorcl.readme file in the / samples 
directory of the VisualAge Generator Server for Solaris product installation 
directory. 



Migrating Applications from Oracle 7 to Oracle 8 

If you have migrated from the Oracle7 for Solaris client to the Oracle8 for 
Solaris client on your Solaris system, two migration paths are available for 
upgrading your VisualAge Generator applications that use the Oracle7 client 
library to use of the Oracle8 client library. Choose one of the following paths, 
depending upon the Oracle8 client/server features you plan on using: 

1 . If you do not want to use any of the new Oracle8 features or you want to 
use new Oracle8 features that do not require recoding of the application, 
relink your VisualAge Generator Oracle7 applications with the Oracle8 
client library. This allows you to take advantage of Oracle8 features such 
as Improved Data Warehouse Performance. 
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A k-shell script is provided with VisualAge Generator Server to help 
automate the relink process. The script is called orarelink and is located in 
the /samples directory of your VisualAge Generator Server for Solaris 
product installation directory. 

The orarelink command syntax is as follows: 

orarelink [-a] [-f filename] [appnamel appname2 ...] [-h[H|?] 

where 

-a Specifies that you would like to relink all applications in the 
current directory (determined by searching for all files named 
*z.scr). 

-f Specifies the name of a file that contains the names of programs to 
relink in the current directory. The file should contain only one 
program name per line. Optional comment lines can be included 
by placing a pound sign (#) at the beginning of the comment line. 

appnamel appnamel ... 

Specify the names of applications (separated by a blank space) that 
you would like to relink. 

hlHI? 

Displays help information for the orarelink command. 

Notes: 

a. You can only specify applications that are in the current directory from 
which you issue the orarelink command. 

b. To issue the orarelink command from any command line, you must 
manually add the / samples subdirectory of the product installation 
directory to your Solaris PATH statement (for example, 

/ opt/vgwgs40/ samples). 

c. The appname parameters are application names, not the names of the 
appnamez.scr files. For example, to relink a VisualAge Generator 
application named TEST1, you would issue the command orarelink 
TEST1. 

d. Even if you do not want to use any of the Oracle8 features, relinking 
is required if you want to use the Oracle8 for Solaris client software 
with your VisualAge Generator applications. 

2. If you want to use new Oracle8 features that require recoding of the 
application, you must recode your VisualAge Generator applications. 
Recoding allows you to take advantage of Oracle8 features such as the 
Object Relational Technology. You must also regenerate and prepare any 
VisualAge Generator applications that you recode. 
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Notes: 

1 . Oracle8 databases can be accessed using VisualAge Generator Oracle7 
applications. If you continue to use the Oracle7 client, no changes are 
necessary. Similarly Oracle7 databases can be accessed using VisualAge 
Generator Oracle8 applications as long as the clients do not use any of the 
Object Relational Technology features of Oracle8. 

2. If you have applications that you have precompiled with the Oracle8 
precompiler, you cannot relink those applications with the Oracle7 client 
SQL library. The precompiler output is not backward compatible. 
However, applications that have been precompiled with the Oracle7 
precompiler can be relinked with the Oracle8 client SQL library. 

For more information on migrating existing Oracle7 precompiler applications 
to Oracle8 precompiler applications, refer to the documentation that came 
with your copy of the Oracle8 for Solaris client. For more information about 
the orarelink tool, see the orarelink.readme file in the / samples directory of 
the VisualAge Generator Server for Solaris product installation directory or 
issue the command orarelink -h. 



204 VisualAge Generator: VisualAge Generator Server Guide for Workstation Platforms 



Chapter 39. Distributing and Running C++ Programs on 
Solaris 



After the compiled program shared library files are placed in a directory on 
your system, the program is ready to be distributed and run on any 
supported system that has Visual Age Generator Server for Solaris installed. To 
run your programs, VisualAge Generator provides the FCWRUN command 
with the /r and /nls options. Solaris is case sensitive so you must type 
commands and parameters in the exact case specified. The FCWRUN 
command and the / r and / nls options are described below. 



FCWRUN Command 

To run a generated and compiled VisualAge Generator main program, enter 
the following command: 
fcwrun progname 

Where progname is the name of the program. Do not include the .si extension. 

Note: If the EZERNLS environment variable has not been set, you must 
specify the / nls parameter. 

You can only run main programs using the fcwrun command. Called 
programs can be run by a call from another VisualAge Generator program or 
a 3GL program. 



Using the /r Option 

You can use the / r optional parameter with the FCWRUN command to 
specify the name of a resource association file. If you do not specify this 
option, the default filename fcw.rsc is used. For example, if the resource 
association filename is progl.rsc, and the program name is progl, use the 
following command: 

fcwrun progl /r=progl.rsc 

The resource association file can be qualified with a path name. If it is not 
fully qualified, it will be searched for in the following locations: 

• The current directory 

• The directories specified by the FCWDPATH environment variable 

You can also specify the resource association file using the FCWRSC 
environment variable. 
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Using the /nls Option 

VisualAge Generator provides a /nls option to specify the language version of 
VisualAge Generator Server you want to use and the program message tables 
to use. To use this option, enter the following command: 
fcwrun mainapp /nls=xxx 

Where a valid NLS code. 

The following are the valid NLS codes for VisualAge Generator Server: 



Valid Code 


Language 


ENU 


English 


DEU 


German 


DES 


Swiss German 


ESP 


Spanish 


PTB 


Brazilian Portuguese 


KOR 


Korean 


JPN 


Japanese 


CHS 


Simplified Chinese 


CHT 


Traditional Chinese 


FRA 


French 


ITA 


Italian 



If / nls=xxx is not specified, the environment variable EZERNLS is checked. 
Either / nls=xxx or EZERNLS must be specified. 
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Part 10. Running VisualAge Generator C++ programs 
on CICS for Solaris 
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Chapter 40. Preparing to Run C++ Programs on CICS for 
Solaris 



After a VisualAge Generator CICS for Solaris program has been generated, the 
generated objects must be moved to a Solaris system and prepared before you 
can run the program. For CICS for Solaris, preparation includes compiling 
and linking the generated C++ programs. The C++ Generator creates the 
control files to send the appropriate source to the remote machine and start 
the make process on that machine. 



Preparing Your CICS for Solaris C++ Programs 

Preparation can be started automatically following the generate process, or it 
can be started manually with the PREPARE subcommand of HPTCMD. See 
the VisualAge Generator Generation Guide for a list of the files involved in the 
preparation process and the syntax of the HPTCMD and PREPARE 
commands. 

Automatic Preparation 

The preparation process is automatically started by generation unless you 
specify the /NOPREP option on the generate command or did not specify 
Start preparation command file in the options notebook. 

Additionally, the following options must be specified for preparation to be 
started: 

• /DBUSER=<SolarisDatabaseUserid> — if using DB2 or Oracle 

• /DBPASSWORD=<SolarisDatabasePassword> — if using DB2 or Oracle 

• /DESTHOST=<SolarisHostName> 

• /DESTUID=<SolarisUserId> 

• /DESTPASSWORD=<SolarisUserPassword> 

• /DESTDIR='<SolarisDirectory>' 

Note: The SolarisDirectory name must be the full path name. The user 
identified by SolarisUserlD must have the following: 

• Rexec authority to the target Solaris host machine 

• Write authority to the destination directory and files 

Manual Preparation 

You can run the preparation process independently from the generation 
process using the PREPARE subcommand. 
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The PREPARE subcommand can be issued only through the VisualAge 
Generator program generator command line interface. The interactive interface 
does not support the PREPARE subcommand. 

The following options are required: 

• /DBUSER=<SolarisDatabaseUserid> — if using DB2 or Oracle 

• /DBPASSWORD=<SolarisDatabasePassword> — if using DB2 or Oracle 

• /DESTHOST=<SolarisHostName> 

• /DESTUID=<SolarisUserId> 

• /DESTPASSWORD=<SolarisUserPassword> 

• /DESTDIR='<SolarisDirectory>' 

Note: The SolarisDirectory name must be the full path name. The user 
identified by SolarisUserlD must have the following: 

• Rexec authority to the target Solaris host machine 

• Write authority to the destination directory and files 



Understanding Preparation Output Files 

The outputs you receive from program preparation are shared object libraries 
(CPPs, SOs) which, along with the .TAB files for tables, constitute the 
executable code for the program. The following executables are created for 
each program: 

progname.cpp 

progname is the name of a main program 

progcall.cpp 

progcall is the name of a called program 

map.so 

map is the name of the main map group 
hip. so hip is the name of the help map group 

The map.so and hip. so are created only if a map group or help map group is 
defined for the program. 

In addition to the .cpp and .so output files, you will receive other files with 
extensions such as .0 and .bnd. The .0 (object) files can be deleted. The .bnd file 
should be saved for binding SQL programs to other databases, if the program 
must be moved to other systems. All the other files are temporary files and 
can be deleted. 



Placing Executables 

The executables created during preparation will be in the directory specified 
in the /DESTDIR option. 
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The generated table files (.tab extension) that the program uses need to be in a 
directory specified in the FCWDPATH environment variable used by CICS for 
Solaris. 

Note: The user CICS must have read and execute authority to the directory. 
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Chapter 41. Customizing Your Workstation to Run C++ 
Programs on CICS for Solaris 



Customizing your Solaris workstation to run CICS for Solaris programs 
requires that the following tasks be performed: 

• Setting environment variables describing the operating environment to the 
running programs 

• Defining transactions, programs, and files to CICS 

In addition, there are the optional tasks of modifying the text of VisualAge 
Generator Server for Solaris messages to meet national language requirements 
and the migration of host files to the workstation. 



Setting Environment Variables 

VisualAge Generator Server for Solaris provides the following environment 
variables that your system administrator can add to the CICS for Solaris 
environment file (/var/cics_regions/$CICSREGION/ environment). 

Table 21. Product Specific Environment Variables for CICS for Solaris 



Environment variable 


Runtime services 




CSOTROPT 


Optional 




CSOTROUT 


Optional 




DB2INSTANCE 


Required (if accessing 


;DB2) 


EZERJULL_xxx 


Optional 




EZERJULS_xxx 


Optional 




EZERGRGL_xxx 


Optional 




EZERGRGS_xxx 


Optional 




EZERNLS 


Required 




EZERSQLDB 


Optional 




FCWDB2DIR 


Required (if accessing 
during prep) 


; DB2) (needed 


FCWDBNOOP 


Optional 




FCWDBPASSWORD 


Required (if accessing 


;DB2) 


FCWDBUSER 


Required (if accessing 


;DB2) 


FCWDPATH 


Required 





FCWFIODB Optional 
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Table 21. Product Specific Environment Variables for CICS for Solaris (continued) 


Environment variable 


Runtime services 


FCWLIBPATH 


Required 


FCWOPT 


Optional 


FCWTRDB_<tranid> 


Optional 


FCWTROPT 


Optional 



FCWTROUT Optional 



A typical CICS environment file might contain the following VAGen 

environment variables: 

CS0TR0PT=2 

CSOTROUT=csotrace.out 

DB2INSTANCE=db2inst6 

DPATH=/opt/vgwgs45 : /opt/vgwgs45/l i b 

EZERNLS=ENU 

EZERSQLDB=sampl e 

FCWDBPASSWORD=vguser 

FCWDBUSER=vguser 

FCWDPATH=/home/vguser/genout 

FCWLIBPATH=/home/vguser/genout 

FCWTR0PT=31 

FCWTROUT=fcwtrace.out 

LANG=en_US 

LD_LIBRARY_PATH=/opt/vgwgs45/l ib:$LD_LIBRARY_PATH 

In addition, the value of EZERSQLDATE (on the generation machine) is used 
during generation to set the DB2 date and time format. 

Refer to "Appendix. VisualAge Generator Environment Variables" on page 245 
for further descriptions of these environment variables. 



Defining Programs to CICS for Solaris 

Before a program can run in the CICS for Solaris environment, the programs, 
transactions, and files must be defined to CICS for Solaris as CICS resource 
definitions. Refer to the CICS Administration Reference for more complete 
information on defining resources to CICS for Solaris. 

The following resource definitions are required: 

• Transaction Definitions (TDs) 

• Program Definitions (PDs) 

• File Definitions (FDs) 

• Transient Data Definitions (TDDs) 
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Sample transaction and program definitions using the cicsadd command are 
created at generation, if the CICSENTRIES=RDO generation option is 
specified. The generated command file is prognameC.SCR. This script file 
must be run manually. Before it is run, the CICS environment variable 
CICSREGION must specify the correct region name and run permission must 
be turned on by issuing the following command: 
chmod +x prognamec.scr 

Transaction Definitions 

A transaction definition is required for the following: 

• Each main program 

• Asynchronous programs that you start through CREATX or that specify the 
RT generation option 

• Programs transferred to with an XFER statement 

• Programs transferred to by non-VisualAge Generator programs 

Program Definitions 

Program definitions are required for each program. The program definition 
should include at least the following attributes: 

PathName 

The directory and file name for the program executable. The file 
extension of xpp should not be included. 

File Definitions 

File definitions are required for access VSAM data set types. 

Transient Data Definition 

Transient data definitions are required for serial program files associated with 
CICS transient data queues in the resource association table. 

Migrating Host Files to CICS for Solaris 

The recommended method to migrate host files to a CICS for Solaris system is 
by using the CICS SFS Diagnostic Tool (cicssdt) or the CICS DB2 Diagnostic 
Tool (cicsddt) provided by CICS for Solaris. These tools provide a means for 
migrating QSAM files from a host to SFS/DB2 on Solaris. (You can use the 
REPRO command to copy the contents of a data set from VSAM to QSAM 
format.) For more information on the cicssdt and cicsddt commands, refer to 
the CICS Administration Reference. 
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Chapter 42. Distributing C++ Programs on CICS for Solaris 



You can distribute a program to multiple workstations using one of the 
following methods: 

• Individual files associated with the prepared program can be transferred to 
other workstations 

• A CICS for Solaris cicsexport command can be used to combine all of the 
programs and resource definitions associated with a program into an export 
file. This export file can be transferred to other workstations and imported 
using the cicsimport command. 

VisualAge Generator tables (tablename.tab), map group shared libraries (.so), 
and data files or database information are not included in the export file and 
must be copied separately. 

Refer to the CICS Administration Reference for more information on distributing 
programs using the cicsexport and cicsimport commands. 
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Chapter 43. Considerations for C++ SQL Programs on 
CICS for Solaris 



The following sections provide information for preparing and running 
programs that access relational databases: 

• Accessing DB2 Databases 

• Accessing Oracle Databases 

• Environment Variables 

• Binding an Access Plan Using DB2 

• Code Page Compatibility 

• Static Versus Dynamic SQL Statements 

• Accessing Distributed Databases 

• CICS for Solaris Syncpoint Coordination 

• CICS for Solaris Consideration for a DB2 File System 

• Oracle for Solaris Version Considerations and Incompatibilities 

• Migrating Applications from Oracle 7 to Oracle 8 

• Performance Considerations 



Accessing DB2 Databases 

VisualAge Generator DB2 support provides direct access to DB2 databases 
without using Datajoiner. By specifying the /DBMS=DB2 generation option, 
the VisualAge Generator program is generated specifically for DB2. Additional 
information on using DB2 is documented in the VisualAge Generator Design 
Guide. 



Accessing Oracle Databases 

VisualAge Generator Oracle support provides direct access to Oracle 
databases without using Datajoiner. By specifying the /DBMS=ORACLE 
generation option, the VisualAge Generator program is generated specifically 
for Oracle. Additional information on using Oracle is documented in the 

VisualAge Generator Design Guide. 

Environment Variables 

The following environment variables are referenced in preparing and running 

a program containing SQL statements: 

DB2INSTANCE 

Specifies the name of the DB2 instance. (Applies to DB2 only.) 



© Copyright IBM Corp. 1992, 1999, 2000 



219 



EZERSQLDB 

Specifies the VisualAge Generator Server default database (DB2 or 
Oracle). 
FCWDBNAME_<tranid> 

Specifies the name of the database (DB2 or Oracle) to be used by a 
specific VisualAge Generator Server transaction program. Tranid is the 
CICS transaction ID. 

Notes: 

1 . For DB2, the name specified is the database alias name. 

2. For Oracle, the name specified must be a service name in the 
tnsnames.ora file. 

FCWDBNOOP 

Specifies that CICS XA definitions are being used for database access. 
VisualAge Generator will not attempt to coordinate CICS and 
database resources but instead allows CICS to handle resource 
coordination. 

FCWTRDB_<tranid> 

The name of the relational database to be used for a specific 
transaction. Where <tranid> is the CICS transaction ID. 

FCWFIODB 

The name of the file system database, if CICS is set up to use a DB2 
file system. You should only specify this environment variable if the 
CICS file system and user DB2 tables are located on different 
databases. 

EZERSQLDATE 

The value of the EZERSQLDATE environment variable during 
generation determines the DB2 date format generated for the 
precompiler step in the appnameZ.scr file. The appnameZ.scr file is 
used to make the program on the Solaris system. 

ORACLE_HOME 

Specifies the directory containing the Oracle software. 

For more information on setting environment variables, see "Appendix. 
VisualAge Generator Environment Variables" on page 245. 

Binding An Access Plan Using DB2 

An access plan must be built for each DB2 database a program uses before an 
SQL program can run successfully. The process is called binding the program. 

The access plan is bound during the preparation process to the database used 
during the precompile step. Use the DB2 BIND command to bind the program 
to other databases. To use the BIND command, have the bind file produced 
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during preparation, progname.BNT), available and issue the following 
command on the DB2 command line when connected to the database to 
which you want to bind the program: 
BIND progname.bnd 

where, 

progname.bnd 

Specifies the name of the bnd file for the program you want to run 

To bind an SQL program, you must have the following authority: 

• READ authority to each table the program uses 

• WRITE authority to each table the program updates 

See your database administrator to get the required authorization. 

Refer to the VisualAge Generator Generation Guide for more information on 
performing binding as part of the program generation and preparation 
process. 



Code Page Compatibility 

All SQL programs that use a relational database must use the same code page. 
When you create an SQL database in DB2 for Solaris, the code page of the 
process that creates the database is associated with the SQL database. 



Static Versus Dynamic SQL Statements 

When unqualified table names are used in the SQL statements of a VisualAge 
Generator program, the implicit table qualification might be different for static 
mode SQL statements than for dynamic mode SQL statements. 

In static mode, SQL statements are resolved when the program is bound. All 
unqualified SQL table names are qualified with the USERID that is logged on 
to the workstation when the bind takes place. 

In dynamic mode, SQL statements are resolved while the program is running. 
All unqualified SQL table names are qualified with the USERID that is logged 
on to the workstation where the program is running. 

Dynamic mode is used in the following situations: 

• When the Execution Time Statement Build option is specified for SQL 
statements in a generated program 

• When the table name of an SQL row record is defined as a host variable 
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For more information on static mode versus dynamic mode, refer to the 
VisualAge Generator Design Guide. 



Accessing Distributed Databases 

The Distributed Database Connection Services for Solaris licensed program 
provides access to any database manager enabled as a Distributed Remote 
Database Architecture (DRDA) server, including all members of the DB2 
product family. 

The DB2 Client Program Enabler for Solaris licensed program provides access 
to DB2 databases residing on other platforms. DB2 CAE for Solaris provides 
access to non-IBM relational databases including Oracle and Sybase databases. 

DDCS for Solaris and DB2 CAE for Solaris provides the same interface for 
binding and running programs that DB2 for Solaris does. Refer to these 
products documentation for more information. 



CICS for Solaris SYNCPOINT Coordination 

By default, CICS for Solaris coordinates commit and rollback of resources 
between CICS and the database manager by sequentially issuing a DB2 
commit/ rollback, followed by a CICS syncpoint syncpoint /rollback. If you are 
using XA support, it is necessary that your system is set up to send a message 
to VisualAge Generator indicating that CICS is coordinating commit and 
rollback between CICS and the database manager. To set up this message link, 
set the FCWDBNOOP environment variable. This will indicate to VisualAge 
Generator not to attempt a DB2 commit / rollback at the end of the unit of 
work. 



CICS for Solaris Considerations for a DB2 File System 

If you have set up CICS to use a DB2 file system versus an SFS file system, 
then you need to take into consideration how this affects your VisualAge 
Generator program. By default, the connection pointing to your DB2 file 
system that was established by CICS will be the active connection. If all of 
your user tables are also on this database, you do not need to worry about 
switching connections to your user databases. This means that you do not 
need to set the FCWFIODB, EZERSQLDB, and FCWTRDB_<tranid> 
environment variables. 

If your user data is on a different database, the user needs to ensure that the 
database connection is active before using the database. It is recommended 
that you have VisualAge Generator handle switching of the connections from 
dormant to active. VisualAge Generator will handle the switching of 
connections, if the following environment variables are set: 
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FCWFI0DB=DB2 filesystem name 
EZERSQLDB=user database name 
FCWTRDB_<tranid>=user database name 

When you start CICS, the DB2 file system database connection will be active 
and all other connections will be dormant. When VisualAge Generator 
attempts a database I/O, VisualAge Generator will set the user database 
connection active, perform the database I/O, and set the DB2 file system 
connection active. VisualAge Generator first uses FCWTRDB_<tranid>, if it is 
available. If not available, VisualAge Generator then uses EZERSQLDB for the 
user database name. 

VisualAge Generator uses temporary storage queues when performing 
printing operations. If you submit multiple, large print jobs, this might cause 
the DB2 file system to lock. 



Oracle for Solaris Version Considerations and Incompatibilities 

VisualAge Generator Server for Solaris ships support for both the Oracle7 and 
Oracle8 client products and can be configured to use either one. The Oracle8 
client is used by default. The Oracle7 and Oracle8 clients cannot be used 
simultaneously. For example, you cannot use the Oracle7 client for one 
application and the Oracle8 client for another without reconfiguring 
VisualAge Generator Server for Solaris in between. 

A VisualAge Generator Server tool called orasetup is provided that allows 
you to configure the version of the Oracle client that VisualAge Generator 
Server should use. The orasetup tool is located in the / samples directory of 
the VisualAge Generator Server for Solaris product installation directory (for 
example, / opt/ vgwgs40/ samples). 

To invoke the orasetup tool, issue the orasetup command from a command 
window within the product installation directory. The syntax is as follows: 
orasetup [ -i 7 | 8 ] [ -o 7 | S ] [ -fcwdir directory ] [-h|n|?] 

where 

-i Specifies the version of Oracle to change to. The default is 7. 

-o Specifies the current version of the Oracle client in use by VisualAge 
Generator Server for Solaris. 

If no value is specified for this option, orasetup checks the /lib 
directory of the VisualAge Generator Server for Solaris product 
installation directory for the version of the Oracle modules that are 
not currently being used. For example, if the files fcworcl7.so and 
csoora7.so exist in this directory, Oracle7 is not currently being used 
by VisualAge Generator Server. Hence, the current version is 8. 
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-fcwdir 

Specifies the VisualAge Generator Server product installation 
directory. The default is /opt/vgwgs40. 

-h I H I ? 

Displays help information for the orasetup tool. 

When the values specified for -o and -i are different, orasetup swaps the 
current version of fcworcl.so and csoora.so for the specified version. 

Notes: 

1 . The FCWDBVERSION environment variable is not used on Solaris. 

2. To issue the orasetup command from any command line, you must 
manually add the / samples subdirectory of the product installation 
directory to your Solaris PATH statement (for example, 

/ opt/ vgwgs40/ samples). 

For more information about the orasetup tool, see the orasetup.readme file in 
the / samples directory of the VisualAge Generator Server for Solaris product 
installation directory or issue the command orasetup -h. 

The VisualAge Generator Server for Solaris Oracle interface modules, 
fcworcl.so and csoora.so, are very sensitive to the version of Oracle for Solaris 
on which they were built versus where they execute. The Oracle8 interface 
modules shipped with VisualAge Generator Server for Solaris were built on 
an Oracle Version 8.0.4 system. The Oracle7 interface modules shipped with 
VisualAge Generator Server for Solaris were built on an Oracle Version 7.3.4 
system. If a VisualAge Generator SQL program is run on a Solaris system 
with a version of Oracle for Solaris at a higher release or maintenance level 
than either 7.3.4 or 8.0.4, it could receive the following message: 

FCW0012E Load Module fcworcl.so cannot be loaded. The return code is 2. 

If you are running a version of Oracle for Solaris at a higher release or 
maintenance level than either 7.3.4 or 8.0.4 and receive message FCW0012E, 
use these steps to correct the error: 

1 . Login as root. 

2. Ensure the ORACLE_HOME environment variable is set to point to the 
product installation directory of the version of the Oracle for Solaris client 
you want to use. 

3. Change to the / samples directory of the VisualAge Generator Server for 
Solaris product installation directory (for example, 

/ opt / vgwgs40 / samples) . 

4. Build the VisualAge Generator Server for Solaris Oracle7 modules using 
this command: 

make -f 1 i nkorcl .mak FCWDBVERSI0N=7 



224 VisualAge Generator: VisualAge Generator Server Guide for Workstation Platforms 



Build the VisualAge Generator Server for Solaris Oracle8 modules using 
this command: 
make -f 1 inkorcl .mak 

Step 4 above builds new versions of either the VisualAge Generator Server for 
Solaris Oracle7 or Oracle8 modules customized for your environment and 
copies the new fcworcl.so and csoora.so files to your VisualAge Generator 
Server for Solaris /lib directory. The existing copies are backed up in the same 
directory and renamed with a .save extension. If you do not wish to have the 
makefile automatically install these files, follow steps 1 through 3 above and 
then do the following: 

1 . To build the VisualAge Generator Server for Solaris Oracle7 modules, type 
the following command at the command prompt: 

make -f 1 inkorcl .mak FCWDBVERSI0N=7 build 

To build the VisualAge Generator Server for Solaris Oracle8 modules, type 
the following command at the command prompt: 
make -f 1 inkorcl .mak build 

2. To install the resulting modules by hand, type the following two 
commands at the command prompt, replacing vgwgs with the path to your 
VisualAge Generator Server for Solaris product installation directory (for 
example, /opt/vgwgs40): 

cp fcworcl.so vgwgs H ib/fcworcl .so 
cp csoora.so vgwgs/] ib/csoora.so 

3. To install the resulting modules using the makefile, type the following 
command at the command prompt: 

make -f 1 inkorcl. mak install 

Note: You do not need to specify FCWDBVERSION with the make 
command in this step. 

For more information about building VisualAge Generator Server for Solaris 
Oracle7 and Oracle8 modules, see the linkorcl. readme file in the / samples 
directory of the VisualAge Generator Server for Solaris product installation 
directory. 



Migrating Applications from Oracle 7 to Oracle 8 

If you have migrated from the Oracle7 for Solaris client to the Oracle8 for 
Solaris client on your Solaris system, two migration paths are available for 
upgrading your VisualAge Generator applications that use the Oracle7 client 
library to use of the Oracle8 client library. Choose one of the following paths, 
depending upon the Oracle8 client/server features you plan on using: 
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1 . If you do not want to use any of the new Oracle8 features or you want to 
use new Oracle8 features that do not require recoding of the application, 
relink your VisualAge Generator Oracle7 applications with the Oracle8 
client library. This allows you to take advantage of Oracle8 features such 
as Improved Data Warehouse Performance. 

A k-shell script is provided with VisualAge Generator Server to help 
automate the relink process. The script is called orarelink and is located in 
the / samples directory of your VisualAge Generator Server for Solaris 
product installation directory. 

The orarelink command syntax is as follows: 

orarelink [-a] [-f filename] [appnamel appname2 ...] [-h|H[?] 

where 

-a Specifies that you would like to relink all applications in the 
current directory (determined by searching for all files named 
*z.scr). 

-f Specifies the name of a file that contains the names of programs to 
relink in the current directory. The file should contain only one 
program name per line. Optional comment lines can be included 
by placing a pound sign (#) at the beginning of the comment line. 

appnamel appnamel ... 

Specify the names of applications (separated by a blank space) that 
you would like to relink. 

hlHI? 

Displays help information for the orarelink command. 

Notes: 

a. You can only specify applications that are in the current directory from 
which you issue the orarelink command. 

b. To issue the orarelink command from any command line, you must 
manually add the / samples subdirectory of the product installation 
directory to your Solaris PATH statement (for example, 

/ opt/vgwgs40/ samples). 

C. The appname parameters are application names, not the names of the 
appnamez.scv files. For example, to relink a VisualAge Generator 
application named TEST1, you would issue the command orarelink 
TEST1. 

d. Even if you do not want to use any of the Oracle8 features, relinking 
is required if you want to use the Oracle8 for Solaris client software 
with your VisualAge Generator applications. 

2. If you want to use new Oracle8 features that require recoding of the 
application, you must recode your VisualAge Generator applications. 
Recoding allows you to take advantage of Oracle8 features such as the 
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Object Relational Technology. You must also regenerate and prepare any 
VisualAge Generator applications that you recode. 

Notes: 

1 . Oracle8 databases can be accessed using VisualAge Generator Oracle7 
applications. If you continue to use the Oracle7 client, no changes are 
necessary. Similarly Oracle7 databases can be accessed using VisualAge 
Generator Oracle8 applications as long as the clients do not use any of the 
Object Relational Technology features of Oracle8. 

2. If you have applications that you have precompiled with the Oracle8 
precompiler, you cannot relink those applications with the Oracle7 client 
SQL library. The precompiler output is not backward compatible. 
However, applications that have been precompiled with the Oracle7 
precompiler can be relinked with the Oracle8 client SQL library. 

For more information on migrating existing Oracle7 precompiler applications 
to Oracle8 precompiler applications, refer to the documentation that came 
with your copy of the Oracle8 for Solaris client. For more information about 
the orarelink tool, see the orarelink.readme file in the / samples directory of 
the VisualAge Generator Server for Solaris product installation directory or 
issue the command orarelink -h. 



Performance Considerations 

Refer to the CICS for Solaris and DB2 for Solaris documentation for more 
information on temporary storage queues when using DB2 as a file system. 
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Chapter 44. Running C++ Programs on CICS for Solaris 



To run a program under CICS for Solaris you must first start a CICS for 
Solaris terminal with the cicsterm command for 3270 terminals or with the 
cicstermp command for printers. 

Refer to the CICS Administration Reference for more information about these 
commands. 

Refer to your CICS for Solaris documentation for other methods for starting 
transactions. 
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Part 11. Running VisualAge Generator C++ programs 
on SCO OpenServer 
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Chapter 45. Preparing to run C++ programs on SCO 
OpenServer 



After a VisualAge Generator SCO program has been generated, the generated 
objects must be moved to a SCO system and prepared before you can rim the 
program. For SCO, preparation includes compiling and linking generated C++ 
programs. The C++ Generator creates the control files to send the appropriate 
source to the remote machine and start the make process on that machine. 

Preparation can be started automatically following the generate process, or it 
can be started manually with the Prepare subcommand of HPTCMD. 



Automatic preparation 

The preparation process is automatically started by generation unless you 
specify the /NOPREP option on the generate command or did not specify 
Start preparation command file in the options notebook. 

Additionally, the following options must be specified for preparation to be 
started: 

• /DESTHOST=<SCOHostName> 

• /DESTUID=<SCOUserId> 

• / DESTPASSWORD=<SCOUserPassword> 

• /DESTDIR='<SCODirectory>' 

Note: The directory must be contained within single quotes and should be the 
full path name. The user must have the following: 

• rexec authority to the target SCO host machine 

• write authority to the destination directory and files 

Manual preparation 

You can run the preparation process independently from the generation 
process using the PREPARE subcommand. 

The PREPARE subcommand can be issued only through the VisualAge 
Generator program generator command line interface. The interactive interface 
does not support the PREPARE subcommand. 

The following options are required: 

• /DESTHOST=<SCOHostName> 

• /DESTUID=<SCOUserId> 



© Copyright IBM Corp. 1992, 1999, 2000 



233 



• /DESTPASSWORD=<SCOUserPassword> 

• /DESTDIR='<SCODirectory>' 



The preparation process in the SCO environment involves transferring the 
source objects (generated source, generated tables, and generated program 
specific utilities) to the target SCO host machine, and remotely invoking the 
compiler and linker on that machine. 

The program can then be run at the target SCO machine, by using the 
following command: 

fcwrun progName 



Generation output files 

The output files created at generation are placed in the generation output 
directory or the current directory if the / GENOUT option is not specified. See 
the VisualAge Generator Generation Guide for a list of these files and how to 
generate them. 



Understanding compiled output files 

The outputs you receive from program preparation are shared object libraries 
(SOs) which, along with the .TAB files for tables, constitute the executable 
code for the program. The following SOs are created for each program: 

progname.so 

progname is the name of a main program 

progcall.so 

progcall is the name of a called program 

map.so 

map is the name of the main map group 
hip. so hip is the name of the help map group 

The map.so and hip. so are created only if a map group or help map group is 
defined for the program. 

In addition to the .so output files, you will receive other files with extensions 
such as .0 and .C. These files are temporary files and can be deleted. 



Placing shared libraries 

The shared libraries created during preparation will be in the directory 
specified in the /DESTDIR generation option. This directory must be in the 
path defined in the LD_LIBRARY_PATH environment variable. 



234 VisualAge Generator: VisualAge Generator Server Guide for Workstation Platforms 



Chapter 46. Customizing your workstation to run C++ 
programs on SCO OpenServer 



This chapter describes the tasks that need to be performed to set up the 
workstation to run SCO programs. These tasks include the following program 
preparation steps: 

• Setting environment variables 

• Creating a resource association file 

Before you can run your programs, you need to set the required environment 
variables for the system. 

If you want to distribute C++ generated programs to other SCO systems, you 
need to set the environment variables on those systems too. 



Defining the environment variables 

VisualAge Generator Server provides the following environment variables that 
you can add to your .profile or you can set them from the SCO command line 
when setting up your environment to run programs. 

You must consider all the SCO environment variables when configuring your 
workstation to run SCO programs. Table 22 shows the product-specific 
environment variables that can be customized for SCO. 

Table 22. Product specific environment variables for SCO 
Environment variable SCO runtime 



CSOTROPT 


Optional 


CSOTROUT 


Optional 


EZEGRGL_xxx 


Optional 


EZEGRGS_xxx 


Optional 


EZEJULL_xxx 


Optional 


EZEJULS_xxx 


Optional 


EZERNLS 


Required 


FCWDPATH 


Optional 


FCWLIBPATH 


Optional 


FCWRSC 


Optional 



FCWOPT Optional 
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Table 22. Product specific environment variables for SCO (continued) 


Environment variable 


SCO runtime 


FCWTROPT 


Optional 


FCWTROUT 


Optional 


PATH 


Required 


LD_LIBRARY_PATH 


Required 



CS0TR0PT=2 

CSOTROUT=csotrace.out 
DB2INSTANCE=db2udb 
DPATH=/opt/vgwgs45 : /opt/vgwgs45/l i b 
EZERNLS=ENU 

FCWDPATH=/usr/vguser/genout 

FCWLIBPATH=/usr/vguser/genout 

FCWTR0PT=31 

FCWTROUT=fcwtrace.out 

LANG=en_US.IS08859-l 

LD_LIBRARY_PATH=/opt/vgwgs45/l ib:$LD_LIBRARY_PATH 
PATH=. :/opt/vgwgs45/bin:$PATH 

In addition, the value of EZERSQLDATE (on the generation machine) is used 
during generation to set the DB2 date and time format. 

Refer to "Appendix. VisualAge Generator Environment Variables" on page 245 
for further descriptions of these environment variables. 



Resource Association File 

If the program you are running accesses files, a resource association file must 
be created, with an entry for each serial record defined in the program. The 
resource association file is also used when your program contains printer 
maps and you want the output directed to a printer queue instead of the 
default output file (appName.map). In the SCO environment, the resource 
association file is used at run time, not at generation time. 

Creating resource association files 

You can create and edit resource association files using a standard editor. You 
can enter options and values in uppercase or lowercase. All of the options can 
span lines. 

Comments are permitted and can appear anywhere in the file. Comments 
begin with the characters /* and end with the characters */. 

The default resource association file name is FCW.RSC. You can override the 
default file name by specifying the /R parameter at rim time or by specifying 
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a filename in the FCWRSC environment variable. For more information on 
using the /R option, see "Chapter 47. Distributing and running C++ programs 
on SCO OpenServer" on page 241. 

The following diagram shows the syntax of the entries in the resource 
association file. 

►* — ASSOCIATE — FILE-filename — , , , , , , ► 

L/FILETYPE=— |— SEQ , ' L/CONTABLeJ L/NOFfJ 

LspoolJ 



-/noreplace — i 

-/REPLACE^^ L/SYSNAME=system resource name-^ \-/SYSTEM=target system-^ 



/text- 



ASSOCIATE 

Associates the file name specified in a record definition or the printer 
file with the physical file that is used for the record at run time 

FILE Specifies the file name in the record for which you are defining 
system resource association information 

The file name can be EZEPRINT (the print file for the program) or 
one of the file names specified for a serial, indexed, or relative record 
used by the program. 

/FILETYPE 

Specifies the implementation of the file in a target environment 

The valid file types are system-dependent. Table 23 on page 239 shows 
the valid file types for each environment. 

The file type can be one of the following: 

SEQ Specifies a serial or print file associated with a system 
sequential file for the SCO environment. 

SPOOL 

Specifies a printer file. The /SYSNAME parameter specifies 
the name of the output queue. 

/NOFF 

Specifies that a form feed should not be issued during Close 
processing for a map. 
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/REPLACE or /NOREPLACE 

Specifies whether an existing serial file is replaced by the new one 
that is written by the program. 

You can specify /REPLACE with file type SEQ for the SCO 
environment. If /REPLACE is specified, the first ADD to a serial file 
in a program, or the first ADD to a serial file following a CLOSE, 
adds the record to the beginning of the file. Previous file contents are 
lost. 

You can use /NOREPLACE to specify that an ADD to a file always 
appends to the end of the file. If /NOREPLACE is specified, ADD 
always adds a record to the end of the current file. /NOREPLACE is 
the default. 

/SYSNAME 

Specifies the system name of the file associated with the file name in 
the record. If /FILETYPE=SPOOL, /SYSNAME specifies an output 
queue name. 

/SYSTEM 

Specifies the target system affected by this associate command 

You might have multiple associates in one resource association file. 
The resource association used is the first association where the value 
specified for the /SYSTEM option matches the value specified for the 
/SYSTEM generation option value. 

The target system value is SCO. 

/TEXT Specifies a special type of serial file that contains line feed (LF) 

characters at the end of each line. When a record is read (SCAN), the 
LF characters are automatically removed. When a record is written 
(ADD), the LF characters are automatically appended to the end of 
each record. This option is useful when exchanging data files with 
other software packages that expect each record to be delimited with 
the LF characters. 

Example of resource association file entries 

Figure 10 shows examples of resource association file entries. 

ASSOCIATE FI LE=FI LEI /SYSTEM=SC0 /FI LETYPE=SEQ 

/SYSNAME=MY FILE. DAT 
ASSOCIATE FILE=EZEPRINT /SYSTEM=SC0 /FILETYPE=SP00L /SYSNAME=PRTQ1 
ASSOCIATE FILE=EZEPRINT /FI LETYPE=SEQ /SYSNAME=PRTMAP.OUT 



Figure 10. Examples of Resource Association File Entries 
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File types supported by environment and record organization 

Table 23 shows the valid file types for the SCO environment. 

Table 23. File types supported by environment and record organization 

Message 

System Indexed Queue Relative Serial Print 

SCO N/A N/A SEQ SEQ 

SPOOL 
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Chapter 47. Distributing and running C++ programs on 
SCO OpenServer 



After the compiled program shared library files are placed in a directory on 
your system, the program is ready to be distributed and run on any 
supported system that has VisualAge Generator Server for SCO installed. To 
run your programs, VisualAge Generator provides the FCWRUN command 
with the / r and /nls options. SCO is case sensitive so you must type 
commands and parameters in the exact case specified. The FCWRUN 
command and the / r and / nls options are described below. 



FCWRUN command 

To run a generated and compiled VisualAge Generator main program, enter 
the following command: 
fcwrun progname 

Where progname is the name of the program. Do not include the .si extension. 

Note: If the EZERNLS environment variable has not been set, you must 
specify the / nls parameter. 

You can only run main programs using the fcwrun command. Called 
programs can be run by a call from another VisualAge Generator program or 
a 3GL program. 



Using the /r option 

You can use the / r optional parameter with the FCWRUN command to 
specify the name of a resource association file. If you do not specify this 
option, the default filename fcw.rsc is used. For example, if the resource 
association filename is progl.rsc, and the program name is progl, use the 
following command: 

fcwrun progl /r=progl.rsc 

The resource association file can be qualified with a path name. If it is not 
fully qualified, it will be searched for in the following locations: 

• The current directory 

• The directories specified by the FCWDPATH environment variable 

You can also specify the resource association file using the FCWRSC 
environment variable. 
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Using the /nls option 

VisualAge Generator provides a /nls option to specify the language version of 
VisualAge Generator Server you want to use and the program message tables 
to use. To use this option, enter the following command: 
fcwrun mainapp /nls=xxx 

Where a valid NLS code. 

The following are the valid NLS codes for VisualAge Generator Server: 



Valid code 


Language 


ENU 


English 


DEU 


German 


DES 


Swiss German 


ESP 


Spanish 


PTB 


Brazilian Portuguese 


KOR 


Korean 


JPN 


Japanese 


CHS 


Simplified Chinese 


CHT 


Traditional Chinese 


FRA 


French 


ITA 


Italian 



If / nls=xxx is not specified, the environment variable EZERNLS is checked. 
Either / nls=xxx or EZERNLS must be specified. 
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Appendix. VisualAge Generator Environment Variables 



To work properly, VisualAge Generator Server and CICS for OS/2 require 
several environment variables to be set. These environment variables can be 
specific to the product or your operating system. For information on 
environment variables that need to be set for VisualAge Generator Server to 
operate with CICS for OS/2, OS/2, AIX, CICS for AIX, CICS for 
Windows NT, Windows NT, HP-UX, Solaris, and CICS for Solaris, refer to the 
VisualAge Generator Installation Guide. 

Environment variables can be set during installation or dynamically at 
runtime. 

Individual programs can require additional environment variables to be set. 
Consider the following environment variables when configuring a workstation 
to run a new program: 

BTRINTF 

Defines the home directory of the File Manager for CICS for OS/2. 
Example 

SET BTRINTF=/H:C:\CICS300\RUNTIME 

CICSCOBCOPY 

Specifies the directories containing COBOL copybooks, such as 
C:\VGSVR45\COPYBOOK and C:\SQLLIB. 

This environment variable is also used by the VisualAge Generator 
templates in the COB2 -I option. This forces IBM VisualAge for 
COBOL for OS/2 to use this variable to search for copy files. 

If your generated programs use SQL, the SQL directory must be 
included on the list of directories specified by the environment 
variable CICSCOBCOPY. 

Example : 

SET CICSC0BC0PY=C:\VGSVR45;C:\SQLLIB 
CICSRGRP 

Specifies a list of CICS program resource groups that CICS for OS/2 
uses at startup. By setting it, you may specify which CICS groups are 
loaded by CICS for OS/2. If it is not set, all CICS groups will be 
loaded. 

Note: If the CICSRGRP environment variable is set, the FAASYS and 
VGSVR45 groups must be included. 
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Example : 

SET CICSRGRP=FAASYS,VGSVR45,APPGRP1 
CICSCOBOL 

Specifies which COBOL to use for compiling transactions. 

Example : 

SET CICSC0B0L=IBM 

CICSRD 

Identifies the path and name of the CICS for OS/2 tables file 
(FAACTFTB.BTR). 

Example : 

SET CICSRD=C:\CICS3G0\RUNTIME\DATA\FAACTFTB.BTR 
CICSWRK 

Specifies the list of directories CICS for OS/2 will use when searching 
for run-time and program dynamic link libraries. This is a CICS for 
OS/2 environment variable. It has the same format as the PATH 
environment variable. 

So that CICS for OS/2 can access VisualAge Generator generated 
programs, CICSWRK must contain the directories which contain any 
DLLs produced by VisualAge Generator preparation. This can be done 
by adding these directories to CICSWRK, or by copying the program 
DLLs to a directory already in CICSWRK. 

COBPATH 

Specifies the directory path to be used by the COBOL run-time 
environment to locate dynamically accessed programs. 

Example : 

SET C0BPATH=C : \ I BMCOBOLADLL; C : \VGSVR45\DLL; 
CSODIR 

Specifies the directory where the CSO.INI file is located. By default, 
this location is the root directory where VisualAge Generator 
Common Services is installed for OS/2 or Windows environments, or 
the root directory where VisualAge Generator Server is installed for 
AIX, HP-UX, and Solaris environments. 

CSOTIMEOUT 

Specifies the length of time in seconds after which a time-out error 
occurs if the server does not respond to the client. The default value is 
30. 

CSOTROPT 

Specifies the level of trace information collected for calls to 
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client/ server programs and database connections. Trace information is 
written to the file named in the CSOTROPT variable. The valid values 
are: 

0 Only errors are traced. 0 is the default. 

1 Only errors are traced. 

2 All client/ server calls and database connections are traced. 
CSOTROUT 

Specifies the output file for trace information collected for calls to 
client/ server programs and database connections. Level of 
information is controlled by the CSOTROPT variable. 

The default value is CSOTRACE.OUT. 

DB2INSTANCE 

Specifies the default instance name. 

Example 

export DB2INSTANCE=db2a 

where db2a is the login name of the instance owner. For more 
information on the DB2INSTANCE environment variable, refer to the 
installation manual for DB2 for ATX, DB2 for HP-UX, or DB2 for 
Solaris. 

DLITROPT 

DLITROPT specifies DL/I tracing options, which are used during 
remote DL/I access when the middleware is provided by Visual Age. 
This environment variable is used on Windows NT and OS/2 and can 
take either of two values: 

0 Only information on DL/I errors is retained in a file identified 
in environment variable DLITROUT. 0 is the default. 

1 Information on all DL/I activity is retained in that file. 

Example : 

SET DLITR0PT=1 

DLITROUT 

DLITROUT specifies the file that receives DL/I trace information 
during remote DL/I access when the middleware is provided by 
VisualAge. If the value is blank or the environment variable 
DLITROUT is not present, VisualAge writes trace information to file 
VAGRMDLI.OUT. This environment variable is used on Windows NT 
and OS/2. 
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If you do a typical install of VisualAge for Java, the file is in directory 
C:\IBMJava\rmtDli; the equivalent directory for VisualAge Smalltalk 
is C:\Program Files\VAST\rmtDli (on Windows NT) and 
C:\VAST\rmtDli (on OS/2). 

Example : 

SET DLITROUT=C:\IBMJava\rmtDl i 

DPATH 

Specifies the directories to search for CSO message tables and 
conversion tables on OS/2, AIX, HP-UX, and Solaris. DPATH should 
contain the following product directories: 

OS/2 C:\VGSVR45 

AIX / usr / lpp / vgwgs45 :/usr/lpp/ vgwgs45 / lib 

HP-UX /opt/vgwgs45:/opt/vgwgs45/lib 

Solaris / opt/vgwgs45:/opt/vgwgs45/lib 

Note: On Windows NT, the PATH environment variable is searched 
for CSO message tables and conversion tables. 

ELAPATH 

Specifies the product directory, such as C:\VGSVR45, where 
VisualAge Generator Server is installed. 

The default location is C:\VGSVR45. This is not a list of directories. 
Specify only one directory and do not end the statement with a 
semicolon (;). 

Example : 

SET ELAPATH=C:\VGSVR45 

ELARTRDB_tttt 

Specifies the name of the relational database to be connected to a 
specific generated program. 

The tttt specifies the CICS for OS/2 transaction ID for the transaction 
requiring access to the relational database. 

Note: For transaction names of less than 4 characters, trailing blanks 
should not be included. For example, if you want to specify a 
database name for a transaction with the transaction name 
ABC, set the following: 
SET ELARTRDB_ABC=ALPHADB 

This environment variable is optional when running the Start CICS 
OS/2 with VisualAge Generator Server Run-time Support program, 
ELARUNC.CMD. 
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If this environment variable does not have a value for the transaction 
being run, a default database will is used. 



Example : 

SET ELARTRDB_MYAP=MYDATA 
EZERGRGL_xxx 

This environment variable specifies the default date edit mask for the 
long version of the Gregorian date. 

The default date edit mask is derived from the system date format. 

This environment variable is used only for VisualAge Generator 
Server. VisualAge Generator Developer uses the Long Gregorian value 
on the Date Formats VAGen Options or Preferences page. 

Example 

In the following example, the default date edit mask is set to 
YYYY-MM-DD. 

SET EZERGRGL_ENU=YYYY-MM-DD 

The long version of the Gregorian mask must contain the following 
parts in any order: 

YYYY 4-digit year 

MM 2-digit month 

DD 2-digit day of month 

The mask parts must be separated by any single-byte nonnumeric 
character except D, M, or Y. 

For example, a mask of YYYY/ MM/ DD is used to display the date 
2000/02/05, February 5, 2000. 

The xxx specifies the NLS language identifier. See EZERNLS for the 
valid languages. 

EZERGRGS_xxx 

This environment variable specifies the default date edit mask for the 
short version of a Gregorian date. 

The default date edit mask is derived from the system date format. 

This environment variable is used only for VisualAge Generator 
Server. VisualAge Generator Developer uses the Short Gregorian value 
on the Date Formats VAGen Options or Preferences page. 

Example 
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In the following example, the default date edit mask is set to 
YY-MM-DD. 

SET EZERGRGS_ENU=YY-MM-DD 

The short version of the Gregorian mask must contain the following 
parts in any order: 

YY 2-digit year 

MM 2-digit month 

DD 2-digit day of month 

The mask parts must be separated by any single-byte nonnumeric 
character except D, M, or Y 

For example, a mask of YY/MM/DD is used to display the date 
00/02/05, February 5, 2000. 

The xxx specifies the NLS language identifier. See EZERNLS for the 
valid languages. 

EZERJULL_xxx 

This environment variable specifies the default date edit mask for the 
long version of a day-of-year date. 

The default date edit mask is derived from the system date format. 

This environment variable is used only for VisualAge Generator 
Server. VisualAge Generator Developer uses the Long Julian value on 
the Date Formats VAGen Options or Preferences page. 

Example 

In the following example, the default date edit mask is set to 
YYYY-DDD: 

SET EZERJULL_ENU=YYYY-DDD 

The long version of the day-of-year mask must contain the following 
parts in any order: 

YYYY 4-digit year 

DDD 3-digit day of year 

The mask parts must be separated by any single-byte nonnumeric 
character except D or Y. 

For example, a mask of DDD- YYYY can be used to display the date 
036-2000, which is February 5, 2000. 
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The xxx specifies the NLS language identifier. See EZERNLS for the 
valid languages. 

EZERJULS_ A A A 

This environment variable specifies the default date edit mask for the 
short version of a day-of-year date. 

The default date edit mask is derived from the system date format. 

This environment variable is used only for VisualAge Generator 
Server. VisualAge Generator Developer uses the Short Julian value on 
the Date Formats VAGen Options or Preferences page. 

Example 

In the following example, the default date edit mask is set to 
YY-DDD. Dates are displayed in the form YY-DDD. 
SET EZERJULS_ENU=YY-DDD 

The short version of the day-of-year mask must contain the following 
parts in any order: 

YY 2-digit year 

DDD 3-digit day of year 

The mask parts must be separated by any single-byte nonnumeric 
character except D or Y. 

For example, a mask of DDD-YY can be used to display the date 
036-00, which is February 5, 2000. 

The xxx specifies the NLS language identifier. See EZERNLS for the 
valid languages. 

EZERNLS 

This environment variable specifies the default national language code 
for VisualAge Generator Server. 

This environment variable is only used for VisualAge Generator 
Server. VisualAge Generator Developer uses the HPTRULES.NLS file. 

The NLS language identifiers for VisualAge Generator Server are 
shown below. 

Code Language 

CHS Simplified Chinese 

CHT Traditional Chinese 5 

DES Swiss German 

DEU German 

ENU US English 
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ESP Spanish 

FRA French 5 

ITA Italian 5 

JPN Japanese 

KOR Korean 

PTB Brazilian Portuguese 

You can change the value of EZERNLS. 

The NLS value is determined as follows: 

1 . If the /NLS option is specified, the language specified by the 
/NLS option is used. 

If the language specified for /NLS is not valid, a message is issued 
with a return code of 16. 

2. If a value is not specified for /NLS, the EZERNLS environment 
variable is checked. 

If the value specified for EZERNLS is not valid, the following 
occurs: 

• A return code of 65283 is issued 

• Messages cannot be displayed 

3. If a value is not specified for either the /NLS option or the 
EZERNLS environment variable, the first language in the default 
NLS file, specified by the VAST_NLS environment variable, is 
used. 

Example 

In the following example, for OS/2, the EZERNLS environment 
variable is set to JPN (Japanese): 
SET EZERNI_S=JPN 

For AIX, if EZERNLS is not specified in your .profile file, the /nls 
parameter is required when you run the program, for example: 
fcwrun progname /nls=enu 

EZERSQLDATE 

This environment variable specifies a 3-character value identifying the 
SQL date and time format for DB2. 

The valid values for SQL date and time formats are as follows: 
DEF Format associated with the current country code 
EUR IBM standard format for Europe 
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ISO Format of the International Organization for Standardization 

JIS Format of the Japanese Industrial Standard 

LOC Format in local form associated with the current country code 

USA IBM standard format for the United States 

The default SQL date and time format is DEF. 

This environment variable is only used for VisualAge Generator 
Server. VisualAge Generator Developer uses the sqlDateTime key in the 
HPTINI file. Refer to the IBM DB2 Command Reference for more 
information on the DateTime parameter for the BIND command. 

Example 

In the following example, the SQL date and time format is set to the 
International Organization of Standards format: 

SET EZERSQLDATE=ISO 
EZERSQLDB 

This environment variable specifies a default database name when 
accessing relational database tables. 

This environment variable is only used for VisualAge Generator 
Server. VisualAge Generator Developer uses the sqlDefaultDatabase key 
in the HPTINI file. See the VisualAge Generator Installation Guide for 
more information. 

You can override the EZERSQLDB value using the /SQLDB option on 
the GENERATE or PREPARE subcommands. 

VisualAge Generator Server for OS/2 

This environment variable is optional when running programs under 
OS/2 environment. The environment variable 
¥CWDBNAME_progname overrides EZERSQLDB for the VisualAge 
Generator program (progname) specified. If neither EZERSQLDB nor 
FCWDBNAME_progname is set during run time, the default value 
used is the DB2 environment variable DB2DBDFT. VisualAge 
Generator environment variables for OS/2 are normally set in the 
config.sys file. 

VisualAge Generator Server for CICS OS/2 

This environment variable is optional when running programs under 
CICS OS/2 environment. The environment variable ELARTRDB_£ranzd 
overrides EZERSQLDB for the VisualAge Generator transaction 
(tranid) specified. If neither EZERSQLDB nor ELARTRDB Jranid is set 
during run time, no default is provided by VisualAge Generator 
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Server. VisualAge Generator environment variables for CICS OS/2 are 
normally set in the ELAENV.CMD file. 

VisualAge Generator Server for AIX 

This environment variable is optional when running programs in the 
AIX environment. The environment variable FCWDBNAME_progname 
overrides EZERSQLDB for the VisualAge Generator program 
(progname) specified. If neither EZERSQLDB nor 
FCWDBNAME_prognfl?we is set during run time, the default value 
used is the DB2 environment variable DB2DBDFT. VisualAge 
Generator environment variables for AIX are normally set in a user's 
.profile file. 

VisualAge Generator Server for CICS on AIX 

This environment variable is optional when running programs in the 
AIX environment. The environment variable FCWTRDB_franzd 
overrides EZERSQLDB for the VisualAge Generator transaction 
(tranid) specified. If neither EZERSQLDB nor FCWTRDB_franz'd is set 
during run time, the default value used is the DB2 environment 
variable DB2DBDFT. VisualAge Generator environment variables for 
CICS on AIX should be set in the CICS environment file. 

VisualAge Generator Server for Solaris 

This environment variable is optional when running programs in the 
Solaris environment. The environment variable 
¥CWDBNAME_progname overrides EZERSQLDB for the VisualAge 
Generator program (progname) specified. If neither EZERSQLDB nor 
FCWDBNAME_prog7iflme is set during run time, the default value 
used is the DB2 environment variable DB2DBDFT. VisualAge 
Generator environment variables for Solaris are normally set in a 
user's .profile file. 

VisualAge Generator Server for CICS on Solaris 

This environment variable is optional when running programs in the 
Solaris environment. The environment variable FCWTRDB_franzd 
overrides EZERSQLDB for the VisualAge Generator transaction 
(tranid) specified. If neither EZERSQLDB nor FCWTRDB_franzd is set 
during run time, the default value used is the DB2 environment 
variable DB2DBDFT. VisualAge Generator environment variables for 
CICS on Solaris should be set in the CICS environment file. 

VisualAge Generator Server for Windows NT 

This environment variable is optional when running programs in the 
Windows NT environment. The environment variable 
¥CWDBNAME_progname overrides EZERSQLDB for the VisualAge 
Generator program (progname) specified.. If neither EZERSQLDB nor 
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FCW~DBNAME_progname is set during run time, the default value 
used is the DB2 environment variable DB2DBDFT. VisualAge 
Generator environment variable for Windows NT are normally set in 
the Control Panel. 

VisualAge Generator Server for CICS for Windows NT 

This environment variable is optional when running programs in the 
CICS for Windows NT environment. The environment variable 
FCWTRDBJram'd overrides EZERSQLDB for the VisualAge Generator 
transaction (transid) specified. If EZERSQLDB or FCWTRDB_franzd is 
set during run time, the default value used is the DB2 environment 
variable DB2DBDFT. VisualAge Generator environment variables for 
CICS for Windows NT should be set in the CICS environment file. 

VisualAge Generator Server for HP-UX 

This environment variable is optional when running programs in the 
HP-UX environment. The environment variable 
FCWDBNAME_progname overrides EZERSQLDB for the VisualAge 
Generator program (progname) specified. If neither EZERSQLDB nor 
FCWDBNAME_progname is set during run time, the default value 
used is the DB2 environment variable DB2DBDFT. VisualAge 
Generator environment variables for HP-UX are normally set in a 
user's .profile file. 

EZERSQLM1 

Specifies the options to start a database again if it was left in an 
uncommitted state. 

The valid values are as follows: 

YES Start the database again 

NO Do not start the database again 

The default value is YES. 

This environment variable is optional when running the Start CICS 
OS/2 with VisualAge Generator Server Run-time Support program, 
ELARUNC.CMD. This environment variable is also used when 
generated programs run. 

Example 

SET EZERSQLM1=N0 

EZERSQLM2 

Specifies whether VisualAge Generator Server runs the BIND utility to 
produce an access plan for a generated COBOL program if the access 
plan is not available. 
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When a generated program that accesses SQL data begins running, 
VisualAge Generator Server verifies whether the SQL access plan is 
available. If it is not, and if the value of EZERSQLM2 is YES, the 
BIND utility runs to build the access plan. 

The valid values are as follows: 

YES Run the BIND utility if needed. 

NO Do not run the BIND utility. 

The default value is YES. 

This environment variable is optional when running the Start CICS 
OS/2 with VisualAge Generator Server Run-time Support program, 
ELARUNC.CMD. This environment variable is used when generated 
programs run. 

The .BND file for the program, which is created when the program is 
prepared, must be located in the same directory as the program. 

Example 

SET EZERSQLM2=N0 

EZERSQLMF 

Specifies where messages from the BIND utility are directed if 
EZERSQLM2 has the value of YES. 

The messages from the BIND utility are written to the OS/2 device or 
file as specified by the value of environment variable EZERSQLMF. If 
you specify a file name, the location of the file defaults to the CICS 
for OS/2 product directory. This CICS for OS/2 executable directory is 
the directory in which CICS for OS/2 is running. 

Messages do not come directly to the screen. Some valid values are as 
follows: 

• Any file name 

• LPT1 

• NUL 

• PRN 

The default value is NUL, which causes the messages to be discarded. 

This environment variable is optional when running the Start CICS 
OS/2 with VisualAge Generator Server Run-time Support program, 
ELARUNC.CMD. 

Example 

SET EZERSQLMF=LPT2 
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EZERSQLUS 

Specifies the access mode for a database when the START USING 
DATABASE service runs for a generated COBOL program. 

The valid values are as follows: 

S Use the database in SHARED mode 

X Use the database in EXCLUSIVE mode. 

The default value is S. 

This environment variable is used when generated programs run. 

This environment variable is optional when running the Start CICS 
OS/2 with VisualAge Generator Server Run-time Support program, 
ELARUNC.CMD. 

Example 

SET EZERSQLUS=X 

FCEOPT 

Specifies an option for the C++ generator. This environment variable 
is used when you are generating for the C++ environments. You can 
specify one or more of the following options: 

• When you are generating on Windows NT for the Windows NT 
environment and using the IBM C++ Compiler V3.6, this option 
causes the compiler's setenv.bat file to be run before the compile 
starts. In addition to setting this environment variable, you must 
include the compiler's bin directory in the Windows NT PATH 
environment variable. 

Example 

SET FCE0PT=1 

FCETROPT 

Specifies trace options for the C++ generation prepare process. This 
environment variable is used when generating for the C++ 
environments. You can specify one or more of the following options: 

1 Turn on trace. 

2 Trace FTP processing. 

4 Bypass REXEC processing. 

8 Perform REXEC processing. 

Example 

SET FCETR0PT=1 
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FCWCOMP 

Specifies the C++ compiler used to compile generated programs. It is 
used for VisualAge Generator Server for Windows NT when you are 
preparing a program. It is not used at runtime. 

The following values are valid: 

MSVC Microsoft Visual C++ Version 5 or 6 

VA36 IBM VisualAge C++ Version 3.6 

FCWDB2DIR 

Specifies the directory where Database 2 for AIX, Database 2 for 
HP-UX, or Database 2 for Solaris is installed. 

Example for AIX 

export FCWDB2DIR=/usr/lpp/db2_01_01_OG0O 

Example for HP-UX or Solaris 

export FCWDB2DIR=/opt/IBMdb2/v5.0 

FCWDBNAME_progname 

Specifies the name of the relational database to be used for running a 
specific program under OS/2, AIX, Windows NT, HP-UX, or Solaris. 
This environment variable allows the database name to be specified 
on a program basis. If FCWDBNAME_prog?iaffxe is not specified, 
EZERSQLDB is used. If EZERSQLDB is not specified, the DB2 
environment variable, DB2DBDFT is used. 

Example for OS/2 or Windows NT: 

SET FCWDBNAME_MYAPP=MYDB 

Example for AIX, HP-UX, or Solaris: 

export FCWDBNAME_DBSERVE=mydb 

FCWDBNOOP 

Specifies whether you want VisualAge Generator Server or CICS to 
issue commits /rollbacks. If this environment variable is set, CICS will 
issue syncpoints to control the unit of work. This environment 
variable is only valid in the CICS environments and must be specified 
if the CICS region is configured with XA-enabled databases. 

Example for AIX: 

export FCWDBN00P=yes 

Example for Windows NT: 

set FCWDBN00P=yes 

FCWDBPASSWORD 

Specifies the password for connecting to a relational database on 
OS/2, Windows NT, AIX, HP-UX, or Solaris. 
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Example 

export FCWDBPASSWORD=abcdef 
FCWDBUSER 

Specifies the user ID for connecting to a relational database on OS/2, 
Windows NT, AIX, HP-UX, or Solaris. 

Example 

export FCWDBUSER=mary 

FCWDBVERSION 

Specifies the version of the database software installed on the 
Windows NT system. This environment variable is used when 
preparing SQL programs for execution under Windows NT. It is also 
used by the orasetup.exe utility when attempting to determine what 
version of the VisualAge Generator Server for Windows NT Oracle 
modules are being used. 

The following values are valid when preparing Oracle SQL programs: 

8 Oracle8 for Windows NT is installed on the Windows NT 

system. 

7 Oracle7 for Windows NT is installed on the Windows NT 

system. 

This environment variable is not used when preparing DB2 or ODBC 
programs. 

Example 

SET FCWDBVERSI0N=8 
FCWDPATH 

Specifies the directories to search for tables and resource association 
files. 

Example for OS/2 or Windows NT: 

SET FCWDPATH=C:\VGSVR45 

Example for AIX, HP-UX, or Solaris: 

export FCWDPATH=/u/mary/genout 

FCWFIODB 

Specifies the name of the database to be used for CICS files when the 
CICS region is configured to use DB2 as a file system instead of SFS. 
For implicit connections, the databases accessed by the program are 
determined by EZERSQLDB and FCWTRDB_fftt. 

Example for AIX 

export FCWFIODB=cicsdb 
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Example for Windows NT 

set FCWFIODB=cicsdb 

FCWLIBPATH 

Specifies one or more directories to search for compiled programs and 
map groups. 

Example 

export FCWLIBPATH=/u/mary/genout 
FCWMAKE 

Specifies the location of the makefile, FCWMAKE. This environment 
variable is used when preparing programs for execution under OS/2 
and Windows NT. 

Example: 

SET FCWMAKE=C:\VGSVR45 
FCWRSC 

Specifies the resource association file. The default resource association 
file name is fcw.rsc. 

Example for OS/2 or Windows NT: 

SET FCWRSC=fcw.rsc 

Example for AIX, HP-UX, or Solaris: 

export FCWRSC=fcw.rsc 

FCWOPT 

Specifies run time options for Server. This environment variable is 
used when executing programs under OS/2, AIX, Windows NT, 
HP-UX, or Solaris. You can specify one or more of the following 
options: 

1 A map field with a date mask can be modified and left blank 

without causing a date validation error. 

FCWTRDBJranzd 

Specifies the name of the relational database to be used for running a 
transaction under CICS. This environment variable allows the 
database name to be specified on a transaction basis. If 
FCWTRDB_frarad is not specified, EZERSQLDB is used. If 
EZERSQLDB is not specified, the DB2 environment variable, 
DB2DBDFT is used. 

FCWTROPT 

Specifies the Server trace option. This environment variable is used 
when executing programs under OS/2, AIX, Windows NT, HP-UX, 
and Solaris. You can specify one or more of the following options: 

0 To turn the off trace 
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1 



To trace entry or exit for program, process, or statement 
groups 



2 



To 



trace CALL XFER DXFR statements 



4 



To 



trace SQL I/O 



8 



To 



trace File I/O 



16 



To 



trace System events 

turn all of the trace options on 



31 



To 



Example 

SET FCWTR0PT=31 

Note: If FCWTROPT is not specified, the trace is not produced. 
FCWTROUT 

Specifies the trace output file. This environment variable is used by 
OS/2, AIX, Windows NT, HP-UX, and Solaris. The default trace 
output file is FCWTRACE.OUT. 

Example for OS/2 or Windows NT 

SET FCWTROUT=myapp.out 

Example for AIX, HP-UX, or Solaris 

export FCWTROUT=myapp.out 

INFORMIXDIR 

Specifies the directory containing the VisualAge Generator software. 
Required for ODBC on AIX, HP-UX, and Solaris. 

Example for AIX 

export INF0RMIXDIR=/usr/lpp/vgwgs45/l ib 

Example for HP-UX or Solaris 

export INF0RMIXDIR=/opt/vgwgs45/l ib 

MDLROOT 

Specifies the directory where the VisualAge Generator Templates is 
installed. This environment variable is used by OS/2 and 
Windows NT. 

Example for OS/2 or Windows NT 

SET MDLR00T=c:\VAST 

ORACLE_HOME 

Specifies the directory containing the Oracle software. Required for 
Oracle on AIX, HP-UX, and Solaris. 
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Example for AIX 

export ORACLE_HOME=/usr/app/oracl e/product/7 .3.4 

Example for HP-UX or Solaris 

export 0RACLE_H0ME=/u01/app/oracl e/product/7 .3.4 

RMTDLI_PARTNER_LU 

Specifies the name of the partner LU alias used during remote DL/I 
access when the middleware is provided by VisualAge. This 
environment variable is used on Windows NT and OS/2. 

Example : 

SET RMTDLI_PARTNER_LU=ZZLU 

RMTDLI_PARTNER_TP 

Specifies the TP name of the remote DL/I server and is used during 
remote DL/I access when the middleware is provided by VisualAge. 
This environment variable is used on Windows NT and OS/2. 

Example : 

SET RMTDLI_PARTNER_TP=ZZTP 

RMTDLI_SERVER_ENV 

Specifies the fully qualified name of the local Server Environment File, 
which is used during remote DL/I access when the middleware is 
provided by VisualAge. The Server Environment File overrides dataset 
names in the JCL that defines an IMS batch job; for details on that file, 
see the User's Guide. This environment variable is used on Windows 
NT and OS/2. 

Example : 

SET RMTDLI_SERVER_ENV=C: WAGEN\serven.txt 
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